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.

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

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]

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.

4.0 KiB Raw Permalink Blame History