From f3685c412d6eb001abaa1e5a78eb7f7545211166 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Fri, 15 May 2026 15:20:34 +0200
Subject: [PATCH] Add repository scope profile

---
 SCOPE.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 SCOPE.md

diff --git a/SCOPE.md b/SCOPE.md
new file mode 100644
index 0000000..6e581df
--- /dev/null
+++ b/SCOPE.md
@@ -0,0 +1,148 @@
+# 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.