Focowiki v0.7.42

Focowiki v0.7.42

Focowiki v0.7.42 improves large-knowledge-base publication correctness by repairing navigation-chain inconsistencies, making publication cleanup lease-safe, and preventing deterministic navigation leaf identity collisions.

This release ensures bounded publication windows remain consistent with navigation leaves that already exist outside the current window. Recoverable publication failures are automatically rebuilt with fresh manifests while preserving completed document-processing results.

Existing source documents and completed model, GraphRAG, embedding, relationship, search, and projection facts are reused. Documents do not need to be uploaded or processed by external providers again.

This release includes all changes since v0.7.39.

Improvements

• Reconciles generated navigation chains before publication activation.
• Normalizes directory navigation state through one shared implementation.
• Separates bounded navigation reads, normalization, identity allocation, and persistence into explicit responsibilities.
• Reserves all persisted navigation leaf identities before allocating new deterministic leaf IDs.
• Keeps navigation leaf identities unique across bounded publication windows.
• Makes publication-output cleanup conditional on current lease ownership.
• Prevents an expired or superseded publication attempt from deleting outputs owned by a newer attempt.
• Preserves valid publication objects and reservations during retry and recovery.
• Rebuilds recoverable publication work with a fresh manifest when its previous navigation chain is invalid.
• Requeues affected document activation work without replaying completed upstream processing stages.
• Adds migrations for navigation-chain reconciliation, publication cleanup recovery, and navigation leaf identity recovery.
• Keeps publication recovery compatible with existing active knowledge-base revisions and pending document work.

Bug Fixes

• Fixes publication jobs failing with navigation_chain_invalid.
• Fixes bounded navigation windows generating a deterministic leaf ID already used by a leaf outside the current window.
• Fixes navigation entries pointing to missing, duplicated, or incorrectly ordered extension leaves.
• Fixes publication cleanup racing with a renewed or successor lease.
• Fixes stale cleanup removing valid outputs required by the current publication attempt.
• Fixes publication retries inheriting an invalid manifest after navigation reconciliation.
• Fixes affected document jobs remaining blocked after a recoverable navigation failure.
• Fixes large knowledge bases repeatedly stopping at publication even though document processing has completed.
• Fixes navigation failures recurring after worker restart or deployment upgrade.
• Fixes publication recovery requiring unnecessary model, GraphRAG, embedding, or search reprocessing.

Performance and Validation

• Navigation identity allocation was validated against persisted leaves outside the bounded projection window.
• PostgreSQL integration coverage verifies navigation-chain recovery and fresh-manifest reconstruction.
• Migration coverage validates:
  • Existing active knowledge-base revisions
  • Failed navigation publications
  • Pending publication items
  • Repeated migration execution
  • Lease-safe output cleanup
  • Deterministic leaf identity allocation
  • Successor publication jobs after recovery
• Production observation after upgrade confirmed:
  • A recovered 123-item publication job committed successfully.
  • Available documents increased from 16,039 to 16,163.
  • Processing documents decreased by the corresponding 124 documents.
  • No new document failures were introduced.
  • The worker immediately continued with the next publication job.
  • S3-compatible object writes completed successfully.
  • Worker leases continued renewing without PostgreSQL lock waits or worker restarts.
• API unit, PostgreSQL migration, repository, navigation renderer, publication recovery, and integration tests passed.
• Linting, type checking, production builds, OpenAPI validation, migration validation, Docker runtime validation, native tokenizer validation, and documentation browser validation passed.
• Stable API and Admin images passed digest-based runtime validation before release promotion.
• Stable images were published for both linux/amd64 and linux/arm64.
• Documentation build and deployment completed successfully.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, document-processing states, generated logical paths, portable knowledge-bundle structure, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

v0.7.42 includes the following database migrations:

• Navigation-chain reconciliation
• Lease-safe publication-window cleanup recovery
• Navigation leaf identity collision recovery

Run migrations before starting the updated services.

Existing v0.7.39–v0.7.41 knowledge bases and source documents do not need to be uploaded again. Active content is preserved, and recoverable publication work is rebuilt against the current knowledge-base revision.

Completed generation-model, GraphRAG, embedding, relationship, search, and document-projection results are reused. Recovery does not repeat external provider work unless the original durable result is unavailable or invalid.

Historical failed publication records may remain available for diagnostics, but they do not block newly recovered publication work.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.42 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.42
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.42

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.39–v0.7.41

Update the source and image versions:

git fetch --tags
git checkout v0.7.42

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.42
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.42

Pull the images, stop the previous services, run migrations, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy.

Durable document processing and publication recovery resume automatically. Existing source documents do not need to be uploaded again.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.42
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.42

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: https://docs.focowiki.com/agent-integration/

Project repository: https://github.com/farozerolabs/focowiki

Full changes: v0.7.39...v0.7.42

Focowiki v0.7.39

Focowiki v0.7.39

Focowiki v0.7.39 replaces the previous multi-coordinator publication pipeline with a simpler, bounded, single-job publication architecture.

This release improves publication continuity for large knowledge bases, removes legacy recovery loops and corpus-scale limits, and ensures recovered work always advances from the currently active knowledge-base revision.

Existing source documents and completed model, GraphRAG, embedding, relationship, and search results are reused. Publication recovery does not require documents to be uploaded or processed by external providers again.

This release includes all changes since v0.7.31.

Improvements

• Replaces the legacy generation, projection-scope, cutover, and recovery coordinators with one bounded publication job.
• Gives each publication job one manifest, one renewable lease, one activation path, and one terminal result.
• Removes obsolete coordinator queues, shadow state, scope ownership, recovery loops, and related runtime code.
• Converts valid unfinished publication work during upgrade without replaying completed document-processing stages.
• Establishes a committed publication baseline when upgrading an existing knowledge base that does not yet have one.
• Reuses valid source, model, GraphRAG, embedding, relationship, search, and projection facts.
• Makes immutable S3-compatible object writes replayable across transient provider failures.
• Adds short renewable publication leases with explicit ownership fencing.
• Cancels and releases incomplete publication work before retrying.
• Adjusts publication concurrency according to worker memory pressure.
• Adds structured diagnostics for publication leases, retries, storage requests, object counts, output counts, memory usage, and activation outcomes.
• Reads only the source and graph records required by the affected publication scope.
• Avoids loading every document in large navigation or relationship directories.
• Normalizes large navigation manifests into stable bounded records.
• Removes obsolete corpus-scale query and activation limits.
• Writes large activation changes in bounded database batches.
• Keeps portable record ordering consistent across generation, validation, PostgreSQL scanning, stable shards, search terms, and Agent traversal.
• Rebases recovered publication work above the active knowledge-base readiness sequence.
• Prevents stale work from activating content against an older knowledge-base revision.

Bug Fixes

• Fixes publication repeatedly stopping after processing a large knowledge base.
• Fixes stale publication work repeatedly failing with publication_page_owner_revision_stale.
• Fixes recovered publication work targeting a readiness sequence lower than the active knowledge-base head.
• Fixes old pending publication items being admitted after a newer publication has already committed.
• Fixes publication recovery loops caused by inconsistent portable record ordering.
• Fixes quarantined generations rebuilding indefinitely with the same renderer contract.
• Fixes an upgraded knowledge base missing the committed baseline required by single-job publication.
• Fixes publication_active_base_changed failures remaining blocked after upgrade.
• Fixes publication retries retaining expired work or continuing after lease ownership is lost.
• Fixes transient S3-compatible storage failures making immutable uploads unrecoverable.
• Fixes large publication retries retaining excessive memory.
• Fixes large directories loading all source pages for navigation-only projection.
• Fixes graph navigation loading unrelated per-file graph documents.
• Fixes large navigation manifests exceeding previous normalization limits.
• Fixes corpus-scale reads and activation writes being rejected by fixed query caps.
• Fixes completed model, GraphRAG, embedding, relationship, and search work being unnecessarily replayed during publication recovery.
• Fixes one deterministic stale revision repeatedly consuming retry attempts.
• Fixes document availability remaining blocked even though all durable upstream processing facts are valid.

Performance and Validation

• Large-directory regression coverage includes a directory with 10,001 direct child pages.
• Portable bundle ordering and recovery were validated with a 20,000-file synthetic benchmark.
• Large navigation manifests are read and activated through bounded database operations.
• Publication object writes support bounded concurrency and replay-safe S3-compatible storage behavior.
• Upgrade validation covers:
  • Existing active knowledge-base heads
  • Missing committed publication baselines
  • Unfinished legacy publication work
  • Repeated migration execution
  • Worker restart and lease recovery
  • Consecutive post-upgrade publication jobs
  • Stale readiness-sequence recovery
• Production-shaped validation confirmed:
  • A 256-document publication job committed successfully on its first attempt.
  • The worker immediately continued with subsequent publication jobs.
  • A following 32-document job also committed successfully on its first attempt.
  • Available document counts advanced after each activation.
  • No new document failures were introduced during the observed publication cycles.
• API unit, PostgreSQL migration, repository, publication activation, restart, S3 compatibility, and clean-bootstrap tests passed.
• Linting, type checking, production builds, OpenAPI validation, migration validation, Compose validation, Docker runtime validation, native tokenizer validation, and documentation browser validation passed.
• Stable API and Admin images passed runtime validation before release promotion.
• Stable images were published for both linux/amd64 and linux/arm64.
• Documentation publishing completed successfully.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, document-processing states, generated logical paths, portable knowledge-bundle structure, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

v0.7.39 introduces a breaking internal publication-storage migration. The old multi-coordinator publication implementation is removed and replaced with the single-job publication model.

Run migrations before starting the updated services.

Existing v0.7.31–v0.7.38 knowledge bases and source documents do not need to be uploaded again. Active content is preserved, and valid unfinished publication work is converted or rebased against the current active knowledge-base revision.

Completed generation-model, GraphRAG, embedding, relationship, search, and document-projection results are reused. The upgrade does not repeat external provider work unless the original durable result is unavailable or invalid.

Historical failed publication records may remain visible in the database for diagnostics, but they do not block newly admitted single-job publication work.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.39 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.39
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.39

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.31–v0.7.38

Update the source and image versions:

git fetch --tags
git checkout v0.7.39

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.39
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.39

Pull the images, stop the previous services, run migrations, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy.

Durable document processing resumes automatically. Existing source documents do not need to be uploaded again.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.39
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.39

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: https://docs.focowiki.com/agent-integration/

Project repository: https://github.com/farozerolabs/focowiki

Full changes: v0.7.31...v0.7.39

Focowiki v0.7.31

Focowiki v0.7.31

Focowiki v0.7.31 makes large-knowledge-base publication bounded, lease-safe, generation-safe, and continuously recoverable.

This release improves large directory, navigation, graph, and semantic projection performance while preventing stale generations, expired leases, recovery collisions, and regressed fact epochs from blocking document availability.

Publication recovery reuses existing source, model, GraphRAG, embedding, relationship, and projection facts. Documents do not need to repeat upstream processing when only publication must be repaired.

This release includes all changes since v0.7.18.

Improvements

• Replaces whole-directory graph projection with bounded, affected-source projection.
• Projects only direct files and child directories required by each graph scope.
• Removes the legacy 10,000-entry navigation and graph projection limits.
• Batch-builds large directory navigation leaves without quadratic CPU growth.
• Limits ordinary publication to persisted affected-source closures and stable delta shards.
• Preserves global directory counts and navigation boundaries across multiple delta windows.
• Reads semantic directory members in bounded batches while retaining relation-only records and child-directory visibility.
• Adds generation-scoped graph-degree overlays for incremental graph updates.
• Adds cooperative lease checkpoints throughout projection execution.
• Fences writes from workers that have lost or superseded their publication lease.
• Replans stranded or incompatible publication work without repeating model, GraphRAG, embedding, or source upload stages.
• Reclaims expired cleanup and revision-purge leases through bounded retry work.
• Automatically remediates generations affected by obsolete navigation, graph, semantic-directory, deadline, or capacity limits.
• Allocates deterministic successor generation identities during publication recovery.
• Keeps recovered publication target epochs at or above the active knowledge-base fact epoch.
• Isolates publication coordinator iteration failures so one failed recovery attempt cannot terminate the worker process.
• Preserves navigation entries for documents included only through relationship closure.
• Keeps document states monotonic while a successor publication generation is prepared and activated.
• Adds structured publication backlog, scope duration, lease-loss, recovery, and status-regression diagnostics.

Bug Fixes

• Fixes large relationship directories failing or consuming memory proportional to the complete directory.
• Fixes directory navigation generation becoming progressively slower as entry counts grow.
• Fixes semantic directory deltas rejecting affected closures containing more than 256 source documents.
• Fixes one actual directory change causing unrelated navigation leaves to be regenerated.
• Fixes disconnected navigation neighborhoods requiring an unbounded directory rebuild.
• Fixes relation-only documents disappearing from generated navigation.
• Fixes projection execution deadlines being treated as permanent provider failures.
• Fixes expired or stranded scope leases leaving publication generations permanently blocked.
• Fixes cleanup and revision-purge work remaining locked after worker interruption.
• Fixes source activation precondition changes causing repeated publication retry loops.
• Fixes already-active source revisions being rejected during incremental publication.
• Fixes obsolete replacement generations re-entering recovery after their facts are already covered by the active head.
• Fixes completed recovery generations repeatedly replaying the same replacement work.
• Fixes remediated capacity failures remaining quarantined after the underlying limit was removed.
• Fixes concurrent recovery attempts selecting the same deterministic successor generation identity.
• Fixes repeated recovery attempts surfacing generation identity conflicts.
• Fixes coordinator-level recovery errors terminating or restarting otherwise healthy worker processing.
• Fixes recovered publication generations targeting an epoch lower than the active knowledge-base head.
• Fixes stale-target generations writing page ownership against a newer active generation.
• Fixes minimum-compatible replanning regressing the target fact epoch.
• Fixes publication stopping even though durable source documents and upstream processing facts remain valid.

Performance and Validation

• A 30,001-entry navigation generation completed in approximately 26 ms.
• A 10,001-entry snapshot containing one actual change updated only the affected leaf.
• Graph-directory integration coverage validated 10,001 direct relationship files.
• Semantic directory delta coverage validated:
  • 314-source production-shaped affected closures
  • 700-source batched directory deltas
• Production-shaped recovery validation confirmed that a stale lower target epoch is superseded and replanned against a newer active head.
• Recovery validation confirmed that the repaired generation activates successfully and subsequent publication generations continue advancing.
• Real document lifecycle E2E coverage included:
  • Upload
  • Replacement
  • Rename and move
  • Deletion
  • Worker restart
  • Search
  • Graph and Related links
  • PostgreSQL
  • Redis
  • S3-compatible storage
  • OpenSearch
• Generated-link validation completed with 130 internal links and 0 broken links in the focused lifecycle E2E.
• Final main-branch test results:
  • API: 325 passing test files, 2,169 passing tests
  • Admin: 27 passing test files, 211 passing tests
  • OKF: 12 passing test files, 139 passing tests
  • Official OKF fixture: 1 skipped test
• Additional validation covered:
  • 34 storage schema contract tests
  • 24 source-to-activation smoke tests
  • 10 PostgreSQL query-plan tests
  • OpenSearch 2.19 compatibility
  • OpenSearch 3.8 runtime compatibility
  • Publication recovery and activation integration
  • Scope lease loss and execution deadline recovery
  • Concurrent and repeated recovery
  • Migration repeatability
• Linting, type checking, production builds, OpenAPI validation, migration validation, PostgreSQL plan validation, Docker runtime validation, native tokenizer validation, and documentation browser validation passed.
• Stable API and Admin images passed runtime validation before their release tags were promoted.
• Stable images were published for both linux/amd64 and linux/arm64, with provenance attestations.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, document-processing states, generated logical paths, portable knowledge-bundle structure, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

v0.7.31 includes database migrations for:

• Large-directory delta projection
• Delta and lease-safe publication
• Runtime recovery and cleanup lease repair

Run migrations before starting the updated services.

Existing v0.7.18–v0.7.30 knowledge bases and source documents do not require re-uploading. Durable document work resumes through the existing document-indexing queue.

Recoverable publication generations reuse valid source, model, GraphRAG, embedding, relationship, search, and projection facts. Recovery does not repeat external provider work unless its original durable result is unavailable or invalid.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.31 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.31
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.31

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.18–v0.7.30

Allow active uploads and document processing to reach a durable state before stopping the existing deployment.

Update the source and image versions:

git fetch --tags
git checkout v0.7.31

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.31
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.31

Pull the images, stop the previous services, run migrations, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy.

Durable document processing and publication recovery resume automatically. Existing source documents do not need to be uploaded again.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.31
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.31

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: [https://doc...

Focowiki v0.7.18 — PostgreSQL Resource Recovery and Publication Continuity

Focowiki v0.7.18

Focowiki v0.7.18 improves large-knowledge-base publication by making temporary PostgreSQL resource exhaustion recoverable, bounded, and non-blocking.

This release prevents PostgreSQL SQLSTATE class 53 resource failures from permanently quarantining publication generations. Publication pressure is reduced automatically while PostgreSQL recovers, then restored gradually without requiring source documents to be uploaded again.

This release includes all changes since v0.7.17.

Improvements

• Adds a dedicated database_resource recovery class for PostgreSQL SQLSTATE 53xxx failures.
• Treats temporary database resource exhaustion as infrastructure retry work instead of a provider failure or permanent publication invariant.
• Persists each projection scope’s next eligible time, resource-failure start time, and resource-failure count.
• Applies durable exponential retry delays from 1 second up to 30 seconds.
• Recomputes a publication generation after 30 minutes of continuous resource failures so one generation cannot hold the publication queue indefinitely.
• Reuses durable document, relationship, projection, model, and embedding facts during generation recomputation.
• Automatically detects and recovers publication generations previously quarantined by PostgreSQL resource errors.
• Processes recoverable quarantines in bounded groups so recovery work cannot monopolize healthy publication work.
• Dynamically halves effective projection concurrency when PostgreSQL reports resource exhaustion.
• Gradually restores projection concurrency after sustained successful work.
• Adds explicit PostgreSQL shared-memory and query parallelism settings to the bundled Docker Compose templates.
• Uses a 512m PostgreSQL shared-memory allocation by default.
• Disables per-query PostgreSQL parallel gather workers by default to avoid multiplying shared-memory demand under concurrent publication.
• Aligns projection eligibility timestamps with the publication event time so newly planned scopes remain immediately claimable.

Bug Fixes

• Fixes PostgreSQL 53100 and related SQLSTATE 53xxx failures permanently quarantining otherwise valid publication generations.
• Fixes temporary database resource pressure being classified as a model or provider retry.
• Fixes database resource retries consuming or exhausting document business attempts.
• Fixes projection capacity remaining too high while PostgreSQL is under shared-memory pressure.
• Fixes one resource-constrained generation repeatedly competing with healthy publication work.
• Fixes previously quarantined resource-failure generations remaining permanently excluded after deployment recovery.
• Fixes newly planned projection scopes being briefly ineligible because their default database timestamp was later than the publication claim timestamp.
• Fixes resource-retry state remaining attached to a scope after it transitions to another terminal or recomputed state.
• Fixes large concurrent projection queries exceeding the bundled PostgreSQL container’s default shared-memory allocation.
• Fixes document availability stopping even though source documents and all durable processing facts remain valid.

Performance and Validation

• Infrastructure retry delays are persisted in PostgreSQL and remain valid across worker restarts.
• Projection concurrency decreases immediately after a database resource error and recovers gradually after successful work.
• Continuous resource failures are bounded by a 30-minute generation lifetime before recomputation.
• Existing valid document and provider facts are reused; recovery does not repeat model, GraphRAG, embedding, or source upload work unnecessarily.
• PostgreSQL shared memory defaults to 512m.
• PostgreSQL max_parallel_workers_per_gather defaults to 0 in the bundled Compose deployment.
• The full API test suite completed with:
  • 314 passing test files
  • 2,086 passing tests
• The complete workspace test suite completed with:
  • 353 passing test files
  • 2,436 passing tests
  • 1 skipped test
• Integration coverage verifies:
  • PostgreSQL resource-failure classification
  • Durable retry eligibility and exponential delay
  • Adaptive publication concurrency
  • Thirty-minute generation recomputation
  • Existing quarantined-generation recovery
  • Scope state cleanup and sibling supersession
  • Fair scope claiming across knowledge bases
  • Consistent publication timestamps
  • Migration repeatability and schema contracts
• Linting, type checking, production builds, OpenAPI validation, migration checks, PostgreSQL query-plan validation, Docker runtime validation, native tokenizer validation, and documentation browser validation passed.
• The stable Docker images passed API-role, Admin runtime, native tokenizer, S3 fixture, OpenSearch compatibility, and health validation.
• Stable API and Admin images were published for both linux/amd64 and linux/arm64, with provenance attestations.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, document-processing states, generated logical paths, portable knowledge-bundle structure, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

v0.7.18 introduces a database migration for durable projection resource-recovery state. Run the migration before starting the updated services.

Existing v0.7.17 knowledge bases and source documents do not require re-uploading. Waiting and processing document work resumes through the existing document-indexing queue.

Publication generations previously quarantined by PostgreSQL SQLSTATE 53000, 53100, 53200, 53300, or 53400 are detected and recovered automatically using their durable document and projection facts.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.18 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.18
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.18

The bundled PostgreSQL defaults are:

POSTGRES_SHM_SIZE=512m
POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER=0

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.17

Allow active document processing to reach a durable state before stopping the existing deployment.

Update the source and image versions:

git fetch --tags
git checkout v0.7.18

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.18
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.18
POSTGRES_SHM_SIZE=512m
POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER=0

If docker-compose.yml was copied from an earlier release, update the PostgreSQL service:

postgres:
  image: postgres:18-alpine
  command:
    - postgres
    - -c
    - max_parallel_workers_per_gather=${POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER:-0}
  shm_size: ${POSTGRES_SHM_SIZE:-512m}

Pull the images, stop the previous services, run migrations, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy.

Durable document work resumes through the document-indexing queue. Recoverable publication generations are released automatically without re-uploading source documents.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.18
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.18

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: https://docs.focowiki.com/agent-integration/

Project repository: https://github.com/farozerolabs/focowiki

Full changes: v0.7.17...v0.7.18

Focowiki v0.7.17 — Scalable Graph Projection and Recovery

Focowiki v0.7.17

Focowiki v0.7.17 improves large-knowledge-base publication by making relationship-graph directory projection incremental, bounded, and recoverable.

This release prevents large graph directories and previously quarantined publication generations from blocking document availability or reducing effective processing throughput.

This release includes all changes since v0.7.16.

Improvements

• Replaces whole-directory graph relationship loading with deterministic cursor-based scanning.
• Streams relationship records into bounded semantic resource packets instead of retaining complete graph directories in memory.
• Preserves stable ordering, sharding, navigation, generated paths, and portable OKF bundle structure.
• Keeps graph projection memory usage bounded as the number of documents and relationships grows.
• Adds automatic bounded recovery for publication generations previously quarantined by graph directory record limits.
• Requeues remediated publication facts without requiring source documents to be uploaded again.
• Processes recovery work in bounded groups so older quarantined generations cannot monopolize the publication coordinator.
• Improves projection-generation failure transitions and supersedes obsolete sibling work consistently.
• Improves publication backlog accounting by excluding scopes whose publication generation is no longer active.
• Adds structured observability for recovered publication generations, released facts, and superseded scopes.

Bug Fixes

• Fixes large relationship directories failing with graph_directory_record_limit_exceeded.
• Fixes graph projection loading an entire directory’s relationship records into application memory.
• Fixes quarantined publication generations remaining permanently excluded after the underlying graph projection limit was removed.
• Fixes stale or obsolete projection scopes contributing to misleading waiting and running backlog counts.
• Fixes failed graph scope generations leaving sibling work eligible to continue against an invalid publication generation.
• Fixes publication recovery work repeatedly competing with healthy document processing.
• Fixes large knowledge bases becoming progressively slower as graph directory relationship counts increase.
• Fixes affected documents remaining unavailable even though their durable source, model, embedding, relationship, and projection facts were still valid.

Performance and Validation

• Graph directory relationships are now read through bounded cursor pages and written incrementally into bounded output shards.
• Application memory no longer scales with the complete relationship count of a graph directory.
• Recovery is limited to 16 quarantined generations per coordinator pass and uses bounded polling when no further recovery work is available.
• Existing valid document and provider facts are reused during projection recovery.
• The full API test suite completed with:
  • 309 passing test files
  • 2,068 passing tests
  • 9 skipped tests
• Integration coverage verifies:
  • Paginated graph directory scanning
  • Stable relationship ordering across page boundaries
  • Incremental semantic packet generation
  • Failed scope transitions and sibling supersession
  • Quarantined publication recovery
  • Publication backlog accounting
  • Graph projection output continuity
• Linting, type checking, production builds, strict OpenSpec validation, OpenAPI validation, migration checks, Docker runtime validation, and documentation browser validation passed.
• The stable Docker images passed native tokenizer, API-role, Admin runtime, S3 fixture, and health validation.
• Stable API and Admin images were published for both linux/amd64 and linux/arm64, with provenance attestations.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, generated logical paths, portable knowledge-bundle structure, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

No new database schema migration is introduced by v0.7.17.

Existing v0.7.16 knowledge bases and source documents do not require re-uploading. Publication generations affected by the previous graph directory record limit are detected and remediated automatically using their durable document and projection facts.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.17 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.17
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.17

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.16

Allow active document processing to reach a durable state before stopping the existing deployment.

Update the source and image versions:

git fetch --tags
git checkout v0.7.17

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.17
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.17

Pull the images, stop the previous services, run migrations, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy.

Durable document work resumes through the document-indexing queue. Publication generations affected by the previous graph directory limit are recovered automatically.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.17
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.17

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: https://docs.focowiki.com/agent-integration/

Project repository: https://github.com/farozerolabs/focowiki

Full changes: v0.7.16...v0.7.17

Focowiki v0.7.15

Focowiki v0.7.15

Focowiki v0.7.15 introduces coherent document publication, ensuring that source pages, navigation, indexes, graph data, relationships, search ownership, and generated knowledge-base content become visible together as one validated generation.

This release also improves document-processing throughput, separates indexing from upload sessions, strengthens generated-object lifecycle management, and fixes projection conflicts, stale-worker writes, incomplete navigation, GraphRAG framing leaks, and repeated retry failures.

This release includes all changes since v0.7.9.

New Features

• Adds coherent, generation-based publication for generated pages, navigation, indexes, graph resources, relationships, and search ownership.
• Assigns every generated knowledge-base path to exactly one authoritative projection scope.
• Adds immutable publication snapshots and dependency-aware scope generation.
• Adds atomic knowledge-base activation after the complete generated closure has passed validation.
• Adds durable projection lease heartbeats and lease-generation fencing.
• Adds a durable cleanup outbox for generated-object and reservation cleanup.
• Adds bounded adaptive publication windows that coalesce ready documents without turning upload sessions into publication batches.
• Adds per-knowledge-base fairness so one busy knowledge base cannot starve unrelated document processing.
• Streams front-layer generation, relationship confirmation, and GraphRAG model requests while preserving structured response validation.
• Adds compatible shadow generation and per-knowledge-base cutover for deployments already using the clean v0.7.12+ document-indexing boundary.

Improvements

• Keeps the previous active generation readable until its complete successor has been validated and activated.
• Makes document state monotonic: a document remains processing until coherent activation and does not regress after becoming available.
• Separates document indexing from upload-session lifecycle after source content has been accepted.
• Allows ready documents to continue through indexing independently of incomplete or expired upload sessions.
• Renders source, directory, graph, index, catalog, and root scopes concurrently according to their actual dependencies.
• Regenerates only affected projection scopes and reuses unchanged immutable objects.
• Uses deterministic event time and immutable snapshot membership so identical inputs produce byte-identical generated output.
• Routes create, replace, rename, move, directory mutation, delete, and same-path recreation through one publication model.
• Keeps deletion and cleanup outside model, GraphRAG, embedding, and active document-processing capacity.
• Retains provider receipts when only projection or activation work must be retried.
• Improves projection pressure accounting and continuously refills available processing capacity.
• Improves generated-object ownership tracking and removal of superseded S3 objects.
• Preserves the current Admin UI layout, wording, settings, filters, and actions.
• Preserves Admin API and Developer OpenAPI routes, response contracts, generated logical paths, and Docker service topology.

Bug Fixes

• Fixes projection_scope_page_conflict caused by multiple scopes producing the same generated path.
• Fixes duplicate _graph/catalog.json producers assembling content from different contributor snapshots.
• Fixes independently completed projection scopes being combined into a mixed or internally inconsistent generation.
• Fixes stale workers persisting or activating output after losing their lease.
• Fixes cleanup failures incorrectly causing an otherwise valid document to fail.
• Fixes completed documents returning to processing because of later projection, cleanup, or stale work.
• Fixes upload-session state preventing accepted documents from completing indexing and activation.
• Fixes expired or interrupted upload sessions leaving document jobs unable to resume independently.
• Fixes page_object_unverified, invalid projection output, and retry loops caused by incomplete generated-object ownership.
• Fixes concurrent generated-object registration and ownership conflicts.
• Fixes failed work reducing effective document-processing capacity.
• Fixes empty _index/pages/** navigation remaining after moving the final document out of a directory.
• Fixes directory navigation failing to converge after rename, move, deletion, and same-path recreation.
• Fixes GraphRAG completion framing leaking into generated entity descriptions.
• Fixes source replacement or rebuild retaining obsolete generated page candidates.
• Fixes knowledge-base deletion leaving publication-owned generated pages, search ownership, Redis state, or S3 objects behind.
• Fixes projection cleanup and deletion foreign-key conflicts that could surface as PostgreSQL 23503 or 23505.
• Fixes model stream activity not extending request liveness during valid long-running generation.

Performance and Validation

• A real 300-document concurrent E2E completed with:
  • 300 available
  • 0 processing
  • 0 failed
  • 300 unique Developer OpenAPI source IDs
• The 300-document run completed in 2,733 seconds, averaging 6.59 documents per minute while primarily limited by the configured external model provider.
• The coherent publication runtime completed 45 publication generations and 6,097 projection scope generations.
• Projection scope duration averaged 1,179 ms, with a 2,945 ms p95.
• No activation contention, deadlock, serialization failure, lock-timeout diagnostic, or stale-worker commit was observed.
• A hot-knowledge-base and quiet-knowledge-base concurrency test allowed the quiet document to become available in 5,191 ms while mutations continued in the busy knowledge base.
• Continuous public reads completed with zero mixed-generation, broken-link, or unavailable-state observations.
• Generated-content validation covered:
  • 4,081 active generated files
  • 2,640 Markdown files
  • 18,235 Markdown links with 0 broken
  • 2,316 Related links
  • 818/818 valid _graph JSON files
  • 20,551 graph targets with 0 broken
  • 0 missing directory-navigation entries
• Search ownership validation found 1,480 active search documents, matching 1,480 PostgreSQL search owners.
• Semantic indexing contained 519 documents.
• Generated-object cleanup reclaimed 2,405 zero-owner _graph objects, totaling approximately 21.2 MB, without deleting a referenced active object.
• Real lifecycle validation covered source replacement, rebuild, rename, cross-directory move, directory rename, deletion, same-path recreation, Worker restart, and final knowledge-base deletion.
• Final cleanup left zero run-owned PostgreSQL knowledge bases, nonterminal jobs, open cleanup actions, Redis keys, search owners, OpenSearch documents, and S3 objects.
• Final automated validation included:
  • Admin: 211 passing tests
  • OKF: 137 tests, with 1 skipped
  • API: 1,907 tests, with 158 skipped
  • Python GraphRAG adapter: 15 passing tests
  • PostgreSQL deletion acceptance: 10 passing tests
• Linting, type checking, builds, migrations, OpenAPI validation, OpenAPI continuity, documentation validation, browser validation, and local-path leak validation passed.
• The stable Docker images passed native tokenizer, API-role, Admin runtime, S3 fixture, and health validation.
• Stable API and Admin images were published for both linux/amd64 and linux/arm64, with build provenance and attestations.

Compatibility and Maintenance

The Admin UI, Admin API, Developer OpenAPI, generated logical paths, model settings, embedding and reranker protocols, supported search providers, and Docker service topology remain unchanged.

Upgrading from v0.7.12–v0.7.14

The v0.7.15 publication migrations are additive for deployments already using the clean document-indexing boundary introduced in v0.7.12.

Existing active generations remain readable while the coherent generation is prepared and activated. Existing source files do not require re-uploading, and projection repair reuses durable model, GraphRAG, embedding, relationship, source, search, and immutable-object receipts where their inputs remain valid.

Run migrations before starting the updated services.

Upgrading from v0.7.9–v0.7.11

This release includes the clean document-indexing boundary introduced in v0.7.12.

A non-empty v0.7.9–v0.7.11 database cannot be migrated in place. Back up any required source data, reset the Focowiki PostgreSQL database and application-owned storage/search state, then start v0.7.15 and upload the source documents again.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

Fresh Installation

git clone --branch v0.7.15 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.15
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.15

Set the required administrator, PostgreSQL, S3-compatible storage, search-provider, and OpenSearch values, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.12–v0.7.14

Allow active uploads and document processing to reach a safe durable state before stopping the existing deployment.

Update the source and image versions:

git fetch --tags
git checkout v0.7.15

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.15
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.15...

Focowiki v0.7.9

Focowiki v0.7.9

Focowiki v0.7.9 improves large-scale document indexing under search-service pressure, bounds generated-object storage growth, restores bilateral related-file links, and makes generation-model relationship analysis faster and more reliable.

This release includes all changes since v0.7.6.

New Features

• Adds overload-aware search indexing that automatically defers work when the configured search service is saturated.
• Adds bounded lifecycle management for generated page candidates, replaced source revisions, and zero-owner S3 objects.
• Adds compact relationship evaluation using the top 10 retrieved candidates and stable candidate identifiers.
• Adds deterministic cleanup of superseded generated objects outside active document-indexing concurrency slots.
• Adds projection of both endpoints of an accepted relationship so related documents remain mutually discoverable.

Improvements

• Removes the fixed product ceiling from configurable search concurrency.
• Bounds actual search activity by document-processing capacity and measured search-service pressure.
• Keeps overloaded search work pending without consuming document retry attempts.
• Allows unrelated document stages to continue while search indexing is temporarily deferred.
• Increases the bundled OpenSearch Java heap default from 512 MiB to 2 GiB.
• Retains only current source revisions and current generated page candidates after activation.
• Moves S3 cleanup outside document-ingestion resource lanes so cleanup does not reduce indexing throughput.
• Uses compact model inputs containing only the relationship information required for a decision.
• Uses stable candidate IDs instead of titles as the relationship-model output identity.
• Disables model reasoning for document relationship analysis and GraphRAG generation requests on compatible OpenAI-style providers.
• Removes provider output-token caps while retaining application-level schema and result validation.
• Keeps Developer OpenAPI routes and public document-reading workflows unchanged.

Bug Fixes

• Fixes search-service overload causing document failures or consuming retry attempts.
• Fixes failed or saturated search requests reducing effective document-processing concurrency.
• Fixes related-file links being projected for only one endpoint of a bilateral relationship.
• Fixes generated pages missing valid Related links after relationship reconciliation.
• Fixes superseded source revisions and generated page candidates retaining unnecessary S3 ownership.
• Fixes repeated document replacement causing generated-object storage to grow continuously.
• Fixes zero-owner generated objects being cleaned inside active ingestion resource slots.
• Fixes invalid relationship-model output being silently discarded and producing unexplained missing links.
• Fixes title-based relationship output losing candidates with ambiguous, duplicated, or normalized titles.
• Fixes model reasoning overhead increasing request latency for structured relationship decisions.
• Fixes output-token limits truncating otherwise valid structured model responses.

Performance and Validation

• Search saturation now applies upstream backpressure and defers indexing without blocking unrelated document stages.
• Search concurrency remains configurable without a fixed product maximum, while active work stays bounded by document concurrency and runtime pressure.
• Generated-object cleanup is asynchronous and does not occupy document-ingestion concurrency slots.
• A real three-document upload completed document indexing, hybrid search, and source readback against PostgreSQL, Redis, MinIO, OpenSearch, the configured generation model, embedding model, and GraphRAG.
• A real ten-document lifecycle test completed with 10/10 documents available and 21 active relationships.
• Repeated document replacement kept the MinIO object count stable at 177 objects.
• A real seven-document constitutional dataset completed with readable bilateral related-file links.
• Direct GraphRAG generation completed successfully with reasoning disabled.
• The API suite completed with 1,815 passing tests and 116 skipped tests.
• The OKF suite completed with 131 passing tests and 1 skipped test.
• Type checking, linting, production builds, OpenAPI validation, migration checks, source-to-activation smoke validation, and documentation browser validation passed.
• The stable Docker images passed native tokenizer, API-role, Worker-role, search initialization, S3 fixture, Admin runtime, and health validation.
• Dependency security auditing completed successfully during release validation.

Compatibility and Maintenance

The Developer OpenAPI surface and public file-reading workflow remain compatible with v0.7.6.

The database migration adds indexes for current generated-page candidates and pending relationship projections. Run the migration before starting the updated API and Worker containers.

Existing current v0.7.x source files and knowledge bases do not require re-uploading. Superseded generated candidates, replaced source revisions, and zero-owner objects are reclaimed through the updated lifecycle.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses the document-indexing architecture and storage contract introduced in v0.7.0.

The bundled OpenSearch heap now defaults to 2 GiB:

OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g

Confirm that the deployment has sufficient memory before using this default. External OpenSearch deployments are not affected by the bundled container heap setting.

Fresh Installation

git clone --branch v0.7.9 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.9
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.9

Set a strong OpenSearch administrator password and review the remaining required values in .env, then start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.7.6

Allow active uploads and document-indexing work to finish or reach a safely retryable state before stopping the existing deployment.

Update the source and Docker Compose template:

git fetch --tags
git checkout v0.7.9
cp docker-compose.yml.example docker-compose.yml

Merge the template manually if docker-compose.yml contains local customizations.

Update the image versions in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.9
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.9
OPENSEARCH_JAVA_OPTS=-Xms2g -Xmx2g

Pull the images, stop the previous services, run the migration, and start the updated deployment:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

After startup, verify that PostgreSQL, Redis, the selected search provider, API, Worker, and Admin services are healthy. Existing retryable document work resumes through the durable document-indexing queue.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.9
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.9

Both images were validated by digest before their release tags were promoted. Published images include build provenance, SBOM metadata, and attestations.

Documentation

Documentation: https://docs.focowiki.com

Deployment guide: https://docs.focowiki.com/deployment/docker-compose/

Developer OpenAPI: https://docs.focowiki.com/openapi/

Agent integration: https://docs.focowiki.com/agent-integration/

Project repository: https://github.com/farozerolabs/focowiki

Full changes: v0.7.6...v0.7.9

Focowiki v0.7.6 — Faster Document Indexing and Better Diagnostics

Focowiki v0.7.6 improves document-indexing throughput, runtime recovery, and production diagnostics across the v0.7 agent-native knowledge-base architecture.

This release keeps the v0.7 storage, OpenAPI, generated knowledge bundle, and deployment model unchanged. Existing clean v0.7.x deployments can upgrade normally by pulling the new images and running the database migration.

Faster Continuous Document Indexing

Document stages now use more accurate independent resource scheduling and capacity accounting.

The worker can refill available stage capacity without waiting for unrelated documents, while model, GraphRAG, projection, search, and activation work remain independently bounded.

This release includes:

• Improved fixed-DAG scheduling and immediate capacity reuse
• Separate resource lanes for CPU, model, GraphRAG, embedding, search, and projection work
• More accurate adaptive pressure and weighted generation limits
• Correct release of resource permits after success, failure, retry, or cancellation
• Improved scope-projector scheduling without blocking unrelated document work
• PostgreSQL indexes for queued document work and retry selection
• Query-plan coverage for large document queues

These changes are especially important for large uploads where thousands of documents are waiting at different processing stages.

More Reliable Failure Recovery

Failed work no longer reduces available processing capacity for unrelated documents.

Retryable document work is returned to the correct stage with bounded backoff, while terminal failures remain visible and do not hold worker slots.

The runtime also refreshes worker settings and available resource capacity without requiring queued documents to restart their entire indexing lifecycle.

Production Diagnostics

Focowiki now records structured, redacted diagnostics when external model or ingestion requests fail.

Diagnostics cover:

• Generation model requests
• Embedding model requests
• Reranker requests
• GraphRAG model processing
• Upload-session finalization
• Document ingestion stages
• Knowledge projection and search indexing failures

Provider diagnostics may include the safe provider host and route, HTTP status, request ID, retry information, provider error classification, model name, document stage, and stable operation identifiers.

Secrets, authorization headers, request bodies, source document content, vectors, and unbounded provider payloads are not written to logs.

Successful provider requests remain quiet so production logs stay focused on actionable failures.

GraphRAG and Model Runtime Stability

GraphRAG execution and model-processing coordination have been hardened for concurrent document ingestion.

This release improves:

• GraphRAG Python worker-pool recovery
• Invalid or interrupted worker replacement
• Generation request failure classification
• Embedding and Reranker retryability handling
• Relationship reconciliation scheduling
• Model-stage observability without exposing provider payloads

A slow or failed GraphRAG request no longer prevents independent relationship or projection work from using available capacity.

Upload and API Continuity

Admin and Developer OpenAPI upload failures now preserve the correct public error classification while emitting richer internal diagnostics.

The Admin generated-file action has also been corrected to use the current generated-file detail route, keeping document processing results directly readable after activation.

The public OpenAPI surface remains compatible with v0.7.5.

Database Migration

v0.7.6 introduces the storage-vnext-v10-document-indexing-throughput runtime generation.

Run the migration before starting the updated API and worker containers:

docker compose pull
docker compose run --rm migrate
docker compose up -d
docker compose ps

The migration adds queue indexes and updates the runtime-generation contract. Existing clean v0.7.x knowledge bases and source documents are preserved.

Direct in-place upgrades from v0.6.x remain unsupported because v0.7 uses a different storage and document-processing architecture.

Docker Images

Versioned and latest images are available for both linux/amd64 and linux/arm64:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.6
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.6

Both images were validated by digest before their release tags were promoted. Published images include build provenance and attestations.

Validation

The release passed:

• Full API and worker test suites
• Type checking, linting, and production builds
• PostgreSQL migration, idempotence, constraint, and query-plan checks
• S3-compatible storage fixtures
• OpenSearch 3.8.0 and maintained OpenSearch 2.19 compatibility checks
• Source-to-activation smoke validation
• Developer OpenAPI continuity and release validation
• API and Admin Docker runtime validation on linux/amd64 and linux/arm64
• Native Chinese tokenizer and GraphRAG runtime validation
• Documentation build, browser validation, and Pages deployment
• Isolated end-to-end document ingestion and generated-content readback

Documentation

• Documentation
• Deployment Guide
• Developer OpenAPI
• Agent Integration

Full changes: v0.7.5...v0.7.6

Focowiki v0.7.5 — A New Architecture for Agent-Native Knowledge Bases

Focowiki v0.7 introduces a completely redesigned architecture for building portable, interconnected, and agent-native knowledge bases.

This release replaces the previous storage, document processing, publication, search, and generated knowledge bundle architecture. It is intended to be deployed as a fresh installation rather than upgraded in place from v0.6.x.

A New Focowiki Architecture

Focowiki now turns source documents into an interconnected knowledge base that can be navigated by people, applications, and AI agents.

The new architecture is built around:

• Continuous per-document indexing
• Interactive links between related documents
• Portable, path-linked knowledge bundles
• Hybrid search with full-document retrieval
• Graph-enhanced knowledge discovery
• A simple Developer OpenAPI for agent integration
• S3-compatible object storage
• PostgreSQL-backed durable state
• OpenSearch or Meilisearch search providers

Continuous Document Indexing

The previous batch publication pipeline has been replaced with continuous document indexing.

Each document moves independently through ingestion, model analysis, relationship coordination, GraphRAG processing, embedding, projection, search indexing, and activation.

Documents become available as soon as their own processing completes. A slow or failed document no longer prevents unrelated documents from progressing.

The runtime has also been simplified into a unified worker architecture, reducing deployment complexity and removing the previous source, publication, and maintenance worker separation.

Interconnected Knowledge Documents

Generated pages are no longer isolated copies of uploaded files.

Focowiki identifies accepted relationships between documents and writes navigable links into the generated knowledge base. Related documents can reference each other, and those links are updated when documents are added, replaced, moved, or deleted.

The generated tree preserves the original source structure while adding navigation across:

• Documents
• Directories
• Machine-readable indexes
• Relationship graph resources

Portable Knowledge Bundles

Every knowledge base produces a portable, file-first bundle containing:

• index.md
• pages/
• _index/
• _graph/
• manifest.json
• generation-log.jsonl

Generated resources use path-based links instead of internal database identifiers. The bundle can therefore be copied, hosted, inspected, and consumed outside Focowiki.

Machine-readable JSON resources use semantic filenames, while Markdown navigation pages provide progressive traversal through large directories and indexes.

Product-specific implementation details are not embedded into the generated knowledge content.

Agent-Native Retrieval

Focowiki uses search to locate relevant documents and then lets agents read the complete original document.

This avoids limiting agents to isolated text chunks. Search remains a discovery mechanism; the source document remains the authoritative content.

Agents can move continuously through the knowledge base using:

1. Knowledge-base discovery
2. Hybrid document search
3. Full-document reading
4. Related-document navigation
5. Graph expansion
6. Stable file and directory traversal

The Developer OpenAPI keeps identifiers and response links continuous so the output of one operation can be used directly by the next.

Search

OpenSearch 3.8.0 is now the bundled default search provider.

Meilisearch remains supported as an alternative provider selected through environment configuration.

Search combines:

• Exact path and title matching
• Lexical retrieval
• Chinese tokenization
• Embedding-based semantic retrieval
• File relationship signals
• Graph retrieval
• Optional Reranker processing

Search results provide stable read actions that lead back to the complete source document.

GraphRAG and Model Processing

Focowiki now supports general-purpose GraphRAG without changing the original document tree.

Graph processing enriches document relationships and search, while generated pages and source documents remain independently readable.

Runtime model configuration supports:

• Generation models
• Embedding models
• Reranker models

The architecture remains domain-neutral. Legal documents are used for validation, but no legal-specific assumptions are embedded into the knowledge model.

OKF 0.2 Support

Generated knowledge bundles align with Open Knowledge Format 0.2 concepts, including optional trust and provenance signals.

OKF metadata remains permissive:

• Standard fields are not required for upload.
• Unknown metadata fields are preserved.
• Documents with incomplete OKF metadata remain usable.
• Missing trust signals remain empty rather than blocking ingestion.

This allows both structured OKF datasets and ordinary Markdown collections to use the same knowledge-base workflow.

Developer OpenAPI

The Developer OpenAPI has been redesigned around complete agent workflows.

It supports:

• Knowledge-base discovery and metadata
• Upload sessions
• Document processing status
• File and directory traversal
• Full source-content reading
• Hybrid search
• Related-document discovery
• Graph overview and expansion
• Document replacement, movement, deletion, and retry
• Operation polling
• Webhook delivery

Interactive OpenAPI documentation and integration guides are included for developers building agents, tools, and external applications.

Storage and Deployment

The new storage architecture uses:

• PostgreSQL for durable state and ownership
• Redis for coordination and runtime work
• S3-compatible storage for source and generated objects
• OpenSearch or Meilisearch for retrieval

Compatible S3 services include self-hosted MinIO and external providers such as Cloudflare R2 and Backblaze B2.

Docker images are published for both linux/amd64 and linux/arm64.

Stability Included in v0.7.5

The v0.7.5 release includes the stabilization work completed across the v0.7 series:

• Improved GraphRAG request validation and error handling
• Prevented GraphRAG work from blocking unrelated documents
• Corrected document processing cancellation and retry behavior
• Improved structured model output handling
• Fixed OpenSearch runtime authorization and data-directory initialization
• Improved Backblaze B2 and generic S3-compatible storage behavior
• Corrected portable index and graph navigation generation
• Improved nested extension navigation
• Fixed document processing list scrolling and runtime status reporting
• Updated CI, Docker, deployment, OpenAPI, and agent integration documentation

Breaking Release

Focowiki v0.7 uses a new storage and processing architecture.

Upgrading directly from v0.6.x is not supported. Deploy v0.7.5 with new empty PostgreSQL, Redis, S3, and search storage, then configure models and import source documents again.

Do not reuse:

• A v0.6.x PostgreSQL database
• Previous Redis runtime state
• Previous generated S3 objects
• Previous search indexes
• Previous knowledge-base identifiers
• Previous model runtime records

Existing source Markdown files can be uploaded into the new installation.

Users already running a clean v0.7.x installation can upgrade normally to v0.7.5. Deployments created before v0.7.4 with bundled OpenSearch may need to rotate the bundled OpenSearch security configuration as described in the deployment guide.

Fresh Installation

git clone --branch v0.7.5 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Configure .env, including secure passwords, public origins, storage, search, and administrator settings.

Use the versioned images:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.7.5
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.7.5

Then start the deployment:

docker compose pull
docker compose run --rm migrate
docker compose up -d
docker compose ps

Documentation

• Documentation
• Deployment Guide
• Developer OpenAPI
• Agent Integration

Full changes: v0.6.18...v0.7.5

Focowiki v0.6.18

Focowiki v0.6.18

Focowiki v0.6.18 adds durable CJK content search, substantially faster projection repair, per-knowledge-base index maintenance, safer storage reconciliation, and stronger lifecycle consistency across uploads, modifications, deletions, publication, and maintenance.

This release includes all changes since v0.6.10.

New Features

• Adds durable full-body search projections with nodejieba-based CJK tokenization.
• Adds dedicated Projection Repair and Lexical Rebuild Worker roles.
• Adds manual and automatic knowledge-base index maintenance.
• Allows administrators to maintain one knowledge base without scheduling maintenance for every knowledge base.
• Reports maintenance requirements, progress, throughput, retries, heartbeats, and estimated completion in the Admin UI.
• Adds indexed generated-object protection and bounded storage reconciliation.
• Adds a manually triggered prerelease Docker channel while keeping stable releases on version Tags.

Improvements

• Improves graph identifier continuity across Developer OpenAPI calls.
• Improves OpenAPI idempotency, pagination, diagnostics, exact-match search, and source-resource operations.
• Bounds broad graph and hybrid search candidate retrieval before relevance scoring.
• Keeps tree queries inside the selected parent directory.
• Adds generation-scoped read caching and consistent active-generation reads.
• Uses deterministic UTF-8 ordering for directory projections and pagination.
• Processes projection repair with durable, set-based, resumable subtasks.
• Improves storage reconciliation throughput through indexed claims, bounded batches, and lease recovery.
• Improves Admin navigation with a shared sidebar and detail layout.
• Improves generated-file previews, long-content scrolling, and safe link handling.
• Updates the English and Chinese product documentation and deployment guidance.

Bug Fixes

• Fixes stale or mixed-generation reads during publication and repair.
• Fixes missing directory entries and incorrect directory statistics after file changes.
• Fixes projection repair ordering differences that could prevent repaired generations from activating.
• Fixes broad graph queries that could time out on large knowledge bases.
• Fixes incomplete upload sessions retaining path reservations or blocking migrations.
• Fixes deletions waiting on projection repair from being lost or permanently blocking upgrades.
• Fixes frozen deletion publications and persisted work handling during compatible migrations.
• Fixes lifecycle conflicts involving concurrent uploads, modifications, deletions, publication, and maintenance.
• Fixes storage-reconciliation lease stalls and concurrent object-registration conflicts.
• Adds sanitized projection-repair failure diagnostics to Worker logs.

Performance and Validation

• Projection repair for 30,000-file and 100,000-file profiles improved by 11.64x and 12.46x.
• Lexical rebuild and projection repair use bounded concurrency, database batches, object writes, and in-flight memory limits.
• Large search, graph, tree, lifecycle, migration, deletion, and storage paths received dedicated scale and integration coverage.
• Sixty interleaved lifecycle scenarios completed without unexpected failures.
• The stable Docker images passed migration, native tokenizer, API, Worker-role, S3 fixture, and runtime health validation.
• Dependency security auditing reported no known vulnerabilities during release validation.

Compatibility and Maintenance

Database migrations 010 through 017 preserve existing knowledge bases, source files, active generations, generated objects, and durable work records.

Existing source Markdown does not require re-uploading. Index maintenance does not call the configured model, and the current active generation remains readable while maintenance runs.

Knowledge-base maintenance defaults to Manual. After upgrading, open each knowledge base and run Maintain index when the Admin UI reports that maintenance is required. Automatic maintenance can be enabled from Admin Settings.

Fresh Installation

git clone --branch v0.6.18 --depth 1 https://github.com/farozerolabs/focowiki.git
cd focowiki

cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

Pin the Docker images in .env:

FOCOWIKI_API_IMAGE=ghcr.io/farozerolabs/focowiki-api:0.6.18
FOCOWIKI_ADMIN_IMAGE=ghcr.io/farozerolabs/focowiki-admin:0.6.18

Start Focowiki:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Upgrading from v0.6.10

Create a coordinated backup and allow active uploads, source processing, publication, deletion, and maintenance work to finish before stopping v0.6.10.

Update the source and Docker Compose template:

git fetch --tags
git checkout v0.6.18
cp docker-compose.yml.example docker-compose.yml

Merge the template manually if docker-compose.yml contains local customizations. The new template adds the projection-repair-worker and lexical-rebuild-worker services.

Add these settings to .env:

PROJECTION_REPAIR_WORKER_DATABASE_POOL_MAX=8
LEXICAL_REBUILD_WORKER_DATABASE_POOL_MAX=8

Update the image versions and run:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml down
docker compose -f docker-compose.yml run --rm migrate
docker compose -f docker-compose.yml up -d
docker compose -f docker-compose.yml ps

Verify that projection-repair-worker and lexical-rebuild-worker are healthy, then run required knowledge-base maintenance from the Admin UI.

Documentation

Documentation: https://docs.focowiki.com

Project repository: https://github.com/farozerolabs/focowiki