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