INTENT

Purpose

This repository exists to provide a markdown-native toolkit and CLI for transforming semi-structured markdown into structured, queryable, and reusable knowledge artifacts.

It defines the contract layer between human-/agent-authored markdown and structured knowledge operations.

Primary Utility

The repository provides a set of composable primitives that:

Parse and interpret markdown as structured data
Validate content against schemas and conventions
Transform, compose, and generate markdown artifacts
Enable querying, extraction, and analysis of document structure
Support templating and automation workflows (deterministic and LLM-assisted)

It turns markdown from plain text into a programmable knowledge substrate.

The current practical usecase matrix is maintained in docs/practical-usecase-relevance.md. That document translates this intent into adoption-oriented scenarios, relevance expectations, and E2E coverage targets.

Intended Users

Developers building tools or systems on top of markdown-based knowledge
Advanced users operating CLI-based knowledge workflows
Automation systems (atm) executing structured document transformations
LLM agents (agt) interacting with structured markdown as a stable interface

Strategic Role in the System

This repository is part of a layered knowledge system with clearly separated responsibilities:

markitect-tool → makes markdown structured and manipulable
kontextual-engine → makes knowledge persistent and operable
infospace-bench → makes knowledge concrete and meaningful

These layers correspond to a deliberate separation of concerns:

Syntax layer — structuring and transforming semi-structured data (markdown)
System layer — operating, persisting, and orchestrating knowledge
Application layer — applying knowledge systems to real-world contexts

This repository occupies the syntax layer and should maintain clear boundaries to the others.

This repository acts as the foundation layer for markdown-based knowledge systems:

It provides provider-neutral primitives for working with structured markdown
It enables higher-level systems to treat markdown as reliable, structured input/output
It supports CLI-first workflows while remaining usable as a library

It is intentionally infrastructure, not platform.

Strategic Boundaries

This repository is not intended to:

Provide a full knowledge management platform, CMS, or ECM
Persist or manage long-lived knowledge systems or projects
Handle multi-format content beyond markdown-native representations
Define domain-specific knowledge models or workflows
Own orchestration, permissions, or service-level concerns

Such responsibilities belong to higher-layer systems (e.g. kontextual-engine, infospace-bench).

Design Principles

Markdown as a protocol Markdown is treated as a structured, machine-interpretable interface
Primitives over products Provide building blocks, not end-user platforms
Composability All capabilities should be chainable and reusable
Deterministic core, extensible intelligence Structure and validation are deterministic; LLM usage is optional and pluggable
CLI-first, library-always Every capability should be usable interactively and programmatically

Maturity Target

A mature version of this repository should:

Provide a stable, minimal core contract for structured markdown operations
Offer a comprehensive CLI toolkit (mkt) for knowledge workflows
Support extensibility via plugins and adapters without core modification
Enable efficient large-scale document processing with caching and incremental updates
Serve as the default foundation for markdown-centric knowledge tooling

Stability Note

Changes to this file represent a deliberate shift in the role of this repository as a foundational toolkit.

Such changes should be rare, as they define the contract relied upon by all higher-level systems.

4.0 KiB Raw Blame History