SCOPE

This file helps humans and agents understand when this repository is useful, what it owns, and where its boundaries stop.

One-liner

markitect-tool is the markdown-native syntax toolkit and CLI for turning semi-structured Markdown into structured, queryable, reusable knowledge artifacts.

Core Idea

This repo treats Markdown as a protocol: human- and agent-authored text can be parsed, validated, transformed, queried, generated, and passed between tools through stable contracts. It owns the Markitect core primitives and keeps them usable both as a Python library and as the mkt command-line tool.

In Scope

Markdown parsing, document models, schema loading, and validation.
Contract checking for practical document classes and quality gates.
Deterministic transforms such as explode/implode, compose/include, query, templating, document functions, and literate weave/tangle.
Runtime context, assessment, memory profile, cache, backend, policy, source, extension, and render/export adapter contracts.
CLI and public library APIs for local Markitect workflows.

Out of Scope

Concrete non-Markdown source format extraction such as EPUB3 or PDF.
Concrete renderer integrations such as Quarkdown execution.
Long-lived knowledge persistence, project orchestration, or governance state.
Public hosting, workflow scheduling, user accounts, or production service operation.
Domain-specific content models beyond reusable examples and contracts.

Relevant When

You need to parse, validate, transform, query, or generate Markdown-based knowledge artifacts.
You are implementing or testing Markitect core contracts.
You need a stable adapter boundary for source importers or render/export plugins.
You want local CLI workflows through mkt.

Not Relevant When

The work is a concrete file-format adapter owned by a native sibling repo.
The work requires running a specific renderer runtime rather than defining the render/export contract.
The problem is cross-repo state coordination, deployment, or governance.
A plain README edit is enough and no structured Markdown behavior is needed.

Current State

Status: active.
Implementation: Python 3.12 package with CLI, tests, examples, docs, and active workplans.
Stability: core behavior is test-covered and evolving through versioned workplans.
Integration: registered in the Custodian State Hub as markitect-tool.

How It Fits

Upstream coordination: Custodian State Hub tracks workplans and repo state.
Downstream adapters: markitect-filter implements source adapters; markitect-quarkdown implements the Quarkdown render/export adapter.
Higher-layer consumers can use Markitect documents as structured knowledge interchange without owning Markitect internals.

Terminology

Preferred terms: document, contract, content class, source adapter, render export adapter, normalized Markdown, memory profile.
Also known as: Markitect core toolkit, mkt.
Potentially confusing terms: "source adapter" means import into normalized Markitect documents; "render/export adapter" means artifact production from Markitect render requests.

markitect-filter - concrete EPUB3 and PDF source-format adapters.
markitect-quarkdown - concrete Quarkdown render/export adapter.
the-custodian - State Hub registration, workplan tracking, and consistency sync.

Getting Oriented

Start with: README.md, INTENT.md, and docs/getting-started.md.
Key directories: src/markitect_tool/, tests/, docs/, examples/, and workplans/.
Entry points: mkt --help, python3 -m pytest, and the public package under src/markitect_tool/.

Provided Capabilities

type: cli
title: mkt
description: Parse, validate, transform, query, and generate structured Markdown artifacts from local workflows.
keywords: [markdown, cli, parse, validate, transform, query]

type: library
title: markitect_core_primitives
description: Python APIs for document models, contracts, content classes, runtime context, memory profiles, and workflow engines.
keywords: [markdown, library, contracts, memory, workflow]

type: contract
title: markitect_adapter_contracts
description: Source adapter and render/export adapter boundaries for native sibling repositories.
keywords: [adapter, source, render, export, contract]

Notes

Run python3 -m pytest after code changes and sync workplan changes through the Custodian State Hub consistency process.

4.6 KiB Raw Blame History