generated from coulomb/repo-seed
138 lines
4.0 KiB
Markdown
138 lines
4.0 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-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.
|