generated from coulomb/repo-seed
111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
# 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**.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|