E2e tests and frist use docs

docs/getting-started.md

@@ -0,0 +1,130 @@
+# 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.