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

---

## Related / Overlapping

- `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

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

```capability
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]
```

```capability
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.