Add repository scope profile

SCOPE.md

@@ -0,0 +1,137 @@
+# SCOPE
+
+> This file helps humans and agents understand when this repository is useful,
+> what it owns, and where its boundaries stop.
+
+---
+
+## One-liner
+
+markitect-quarkdown provides the concrete Quarkdown render/export adapter for
+Markitect while keeping Quarkdown runtime behavior outside the core toolkit.
+
+---
+
+## Core Idea
+
+This repo bridges Markitect render/export requests to Quarkdown execution. It
+maps Markitect profiles to Quarkdown profiles, builds controlled execution
+plans, models runtime permissions, validates generated artifacts, and exposes
+the adapter through the Markitect render/export entry point.
+
+---
+
+## In Scope
+
+- `render.quarkdown` adapter descriptor and package entry point.
+- Markitect profile to Quarkdown profile mapping.
+- Controlled Quarkdown CLI execution plan construction.
+- Permission and runtime dependency documentation.
+- Generated artifact validation, checksums, examples, and integration metadata.
+
+---
+
+## Out of Scope
+
+- Forking, reimplementing, or vendoring Quarkdown.
+- Markitect core render/export contract ownership.
+- Source extraction from EPUB3, PDF, or other input formats.
+- Public rendering services, hosting, or remote job orchestration.
+- Making `markitect-tool` depend directly on Quarkdown.
+
+---
+
+## Relevant When
+
+- You need Markitect render/export behavior backed by Quarkdown.
+- You are testing adapter-boundary behavior with fake or real Quarkdown runtime
+  execution.
+- You need profile, permission, runtime, or generated artifact handling for
+  Quarkdown outputs.
+- You are maintaining the `render.quarkdown` adapter entry point.
+
+---
+
+## Not Relevant When
+
+- The work changes the generic Markitect render/export contract.
+- The task is source normalization before a Markitect document exists.
+- The desired renderer is not Quarkdown.
+- You only need core Markdown parsing, querying, or validation.
+
+---
+
+## Current State
+
+- Status: active.
+- Implementation: Python 3.12 package with adapter code, docs, examples,
+  integration metadata, and tests.
+- Stability: fake-execution adapter tests are covered; real runtime smoke tests
+  skip when `quarkdown` is unavailable.
+- Integration: registered in the Custodian State Hub as
+  `markitect-quarkdown`.
+
+---
+
+## How It Fits
+
+- Upstream contract: `markitect-tool` owns render/export adapter interfaces.
+- Runtime dependency: Quarkdown CLI provides concrete rendering behavior when
+  installed.
+- Adjacent repo: `markitect-filter` owns source adapters on the input side.
+
+---
+
+## Terminology
+
+- Preferred terms: render/export adapter, Quarkdown profile, execution plan,
+  permission mapping, generated artifact.
+- Also known as: Quarkdown Markitect adapter.
+- Potentially confusing terms: "profile" here is a render/export configuration
+  profile, not a user profile.
+
+---
+
+## Related / Overlapping
+
+- `markitect-tool` - owns core render/export adapter contracts.
+- `markitect-filter` - owns concrete source-format adapters.
+- `the-custodian` - State Hub registration, workplan tracking, and consistency
+  sync.
+
+---
+
+## Getting Oriented
+
+- Start with: `README.md`, `docs/adapter-boundary.md`, and
+  `docs/profile-matrix.md`.
+- Key directories: `src/markitect_quarkdown/`, `tests/`, `docs/`,
+  `integration/`, and `workplans/`.
+- Entry point:
+  `markitect_quarkdown.adapter:quarkdown_adapter_descriptor`.
+
+---
+
+## Provided Capabilities
+
+```capability
+type: render_export_adapter
+title: render.quarkdown
+description: Produce Quarkdown-backed render/export execution plans and artifact metadata for Markitect requests.
+keywords: [quarkdown, render, export, adapter, artifacts]
+```
+
+```capability
+type: integration
+title: quarkdown_runtime_boundary
+description: Document and validate Quarkdown runtime permissions, profile mapping, and generated artifact checksums.
+keywords: [quarkdown, runtime, permissions, profiles, checksums]
+```
+
+---
+
+## Notes
+
+Run tests with `PYTHONPATH=src:/home/worsch/markitect-tool/src python3 -m
+pytest` from this checkout. Real Quarkdown smoke coverage depends on a local
+`quarkdown` command being available.