markitect-tool/docs/getting-started.md

Getting Started

This guide gets from a checkout to practical Markitect use without requiring a service, database server, LLM provider, or project configuration.

Install For Local Use

From the repository root:

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

When working from a checkout without installing:

PYTHONPATH=src python3 -m markitect_tool --help

Add Shell Completion

Generate completion for your shell:

mkt completion bash --instructions
mkt completion zsh --instructions
mkt completion fish --instructions

For Bash, the direct form is:

mkt completion bash > ~/.mkt-complete.bash
echo '. ~/.mkt-complete.bash' >> ~/.bashrc

First Useful Commands

Parse a Markdown file:

mkt parse README.md --format tree

Check document size and complexity:

mkt metrics examples/documents/adr-valid.md

Validate a document contract:

mkt contract check examples/documents/adr-valid.md \
  --contract examples/contracts/adr.contract.md

Query a section:

mkt query examples/documents/adr-valid.md 'sections[heading=Decision]' --format text

Build and search a local index:

mkt cache index examples/documents --root .
mkt search contracts --root . --limit 5

Generate from a template:

mkt template render examples/templates/adr-summary.template.md \
  --data examples/templates/adr-summary.data.yaml

Run a declarative workflow in plan mode:

mkt workflow plan examples/workflows/adr-release-notes.workflow.md \
  --output-dir /tmp/markitect-out

Create an inspectable context package:

mkt context pack contracts --search --root . --max-items 5 --format yaml

Discover The Surface

List built-in extension descriptors:

mkt extension list
mkt extension commands
mkt extension inspect memory.context-package

Regenerate reference docs from the live implementation:

mkt docs cli --output docs/cli-reference.md
mkt docs api --output docs/api-reference.md

Suggested First Workflow

1. Start with mkt parse and mkt metrics on one document.
2. Use mkt contract check with one of the example contracts.
3. Use mkt query or mkt extract to grab a section.
4. Move to mkt cache index and mkt search once you have a directory.
5. Use mkt workflow plan before writing workflow outputs.
6. Use mkt extension commands when looking for the command attached to a capability.

Diagnostics

Most validation-oriented commands return structured JSON or YAML when requested:

mkt contract check examples/documents/adr-invalid.md \
  --contract examples/contracts/adr.contract.md \
  --format json

Use machine-readable output in automation, and text output for quick local inspection.