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

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

When working from a checkout without installing:

```bash
PYTHONPATH=src python3 -m markitect_tool --help
```

## Add Shell Completion

Generate completion for your shell:

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

For Bash, the direct form is:

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

## First Useful Commands

Parse a Markdown file:

```bash
mkt parse README.md --format tree
```

Check document size and complexity:

```bash
mkt metrics examples/documents/adr-valid.md
```

Validate a document contract:

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

Query a section:

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

Build and search a local index:

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

Generate from a template:

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

Run a declarative workflow in plan mode:

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

Create an inspectable context package:

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

## Discover The Surface

List built-in extension descriptors:

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

Regenerate reference docs from the live implementation:

```bash
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:

```bash
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.