generated from coulomb/repo-seed
149 lines
4.6 KiB
Markdown
149 lines
4.6 KiB
Markdown
# 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.
|