generated from coulomb/repo-seed
131 lines
2.7 KiB
Markdown
131 lines
2.7 KiB
Markdown
# 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.
|