# 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.