ledgerwerk

Architecture

WikiMason keeps deterministic wiki logic in Python and exposes a filesystem-backed CLI with configurable tool profiles. Runtime bridge commands are not part of the product surface.

Purpose and constraints

  • Single package at repository root: wikimason/.

  • Python 3.10+.

  • Minimal runtime dependencies: Typer, Click, PyYAML, RapidFuzz, fuzzysearch, and tomli for Python < 3.11.

  • Deterministic local filesystem operations.

  • No upstream Obsidian CLI dependency.

Main layers

CLI

Typer-based command surface with consistent --format text|json output and structured exit codes.

Operational log

Wiki/log.md is an append-only operational timeline with typed events, automatic command logging for important change/audit commands, log tail, and log check validation.

Config and profile

TOML configuration resolved from explicit --config, local wikimason.toml, --env profiles, and built-in defaults. The active profile (Markdown, Obsidian, or Logseq) controls on-disk page layout, frontmatter format, and link rendering.

Filesystem

Profile-aware page path resolution, safe vault-relative file operations, and structured directory layout with Raw/, Wiki/, Schema/, and _templates/.

Source lifecycle

Import raw sources with content hashing and stable source_id assignment. Manifest tracking in Schema/source-manifest.jsonl. Scan, delta, verify, rehash, and lint operations.

Build and lint

Compile AGENTS.md from schema, policy, and command metadata. Generate and validate indexes, catalogs, and command references. Lint pages for schema compliance, link integrity, and source parity.

Search

Catalog-based keyword and fuzzy search across compiled wiki pages.

Runtime workflows

Init

wikimason init <profile> <path> scaffolds a complete vault with directories, templates, schema files, git hooks, and AGENTS.md.

Source ingest

wikimason source add → source scan → source delta → ingest status → ingest plan → note new → ingest finish.

Vault maintenance

wikimason vault maintain verifies, rebuilds, scans, lints, and audits all tracked state in one pass, then validates the operational log.

Generated artifacts and ownership

These files are generated by WikiMason and should not be hand-edited:

  • Schema/source-manifest.jsonl

  • Schema/command-reference.md

  • Schema/frontmatter-schema.md

  • Schema/agent-workflow.md

  • Wiki/catalog.jsonl

  • Wiki/index.md

  • Wiki/log.md

  • AGENTS.md