# markitect-tool

`markitect-tool` is a markdown-native toolkit and CLI for turning
semi-structured Markdown into structured, queryable, reusable knowledge
artifacts.

This repository is the syntax-layer successor to the in-scope core of
`markitect-main`. Its product boundary is defined in `INTENT.md` and the
requirements documents in `wiki/`.

## Start Here

- `INTENT.md` - project purpose, boundaries, and design principles
- `wiki/ProductRequirementsDocument.md` - product scope and success criteria
- `wiki/FunctionalRequirementsSpecification.md` - observable functional behavior
- `docs/markitect-main-scope-assessment.md` - migration assessment from `markitect-main`
- `docs/practical-usecase-relevance.md` - practical adoption usecases and relevance expectations
- `docs/getting-started.md` - first-use guide from checkout to practical commands
- `docs/command-cheatsheet.md` - command-oriented workflow cheat sheet
- `docs/examples-index.md` - map from examples to usecases and commands
- `docs/source-adapter-contract.md` - v1 source adapter contract for external format adapters
- `docs/source-adapter-migration.md` - sibling-repo handoff for source adapter adoption
- `docs/performance-notes.md` - local performance posture and smoke coverage
- `docs/cli-reference.md` - generated `mkt` command reference
- `docs/api-reference.md` - generated public API reference
- `workplans/` - source-of-truth implementation and migration plans

## State Hub

The repo is registered with the Custodian State Hub as `markitect-tool` under
the `markitect` domain. See `docs/state-hub-integration.md`.

## Development

Run the tests:

```bash
python3 -m pytest
```

Install locally from a checkout:

```bash
python3 -m pip install -e .
mkt --help
```

Try the parser CLI from a checkout:

```bash
PYTHONPATH=src python3 -m markitect_tool parse README.md --format tree
```

Generate shell completion and reference docs:

```bash
mkt completion bash > ~/.mkt-complete.bash
mkt docs cli --output docs/cli-reference.md
mkt docs api --output docs/api-reference.md
```