• Alpha: monitor, vault, transform, diff layers are under active development; CLI and MCP may change without notice.
• Upcoming priorities and ideas: NEXT.md.

Mutation Testing: Tests the quality of our test suite by introducing small changes (mutations) to the code and verifying that existing tests catch them. A score of 56.2% means 56.2% of introduced mutations were successfully killed by the test suite.

Test Statistics: 648 tests across 112 test files.

WKS provides intelligent filesystem monitoring, vault link tracking, and document transformation capabilities. Built as a layered architecture with MongoDB backend and Model Context Protocol (MCP) integration for AI assistants.

Important Note: WKS is currently in alpha development status and is not yet ready for external users. Our immediate focus is on comprehensive revision and ensuring 100% test coverage across existing features.

Core Capabilities:

• Filesystem Monitoring: Priority-based file tracking with automatic indexing
• Vault Link Management: Bidirectional link tracking for Obsidian vaults
• Transform Layer: Document conversion (PDF → Markdown) with intelligent caching
• MCP Server: AI assistant integration via Model Context Protocol
• Service Daemon: Background monitoring with automatic sync

Global Options: --version / -v, --display json|yaml (default: yaml), --help / -h

• Python 3.12, 3.13, or 3.14
• MongoDB 4.0+
• macOS/Linux

# Clone and setup
git clone https://github.com/wawiesel/wks.git
cd 2025-WKS

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e '.[all]'

# Optional: Install docling for PDF/Office transformation
pipx runpip wksc install docling

wksc config

wksc service start

wksc service status

wksc vault sync

wksc vault links ~/vault/Note.md

## MCP Integration

Install for AI assistants:
```bash
wksc mcp install  # Install for all clients
wksc mcp install --client cursor --client claude

Available tools: wksm_* (see qa/specs/wks.md for details)

The system's architecture is designed in layers, with core functionality currently implemented and under revision up to the Indexing Layer as described in the specifications.

See qa/specs/wks.md for the complete system specification.

Key Layers (Implemented & Under Revision):

• Monitor Layer: Filesystem state tracking
• Vault Layer: Knowledge graph links
• Transform Layer: Document conversion
• Diff Layer: File comparison engines
• Service Layer: Background daemon
• Index Layer: Building towards comprehensive search indices (conceptualized in SPEC.md)

• CONTRIBUTING.md: Development & Testing Guide
• docker/README.md: CI Docker Image Guide
• qa/specs/wks.md: The complete system specification and architectural overview.
• NEXT.md: Current development priorities and high-level roadmap.
• AGENTS.md: Specific directives and guidelines for AI agents working on this project.
• LICENSE.txt: Project license details.