E2e tests and frist use docs

docs/command-cheatsheet.md

@@ -0,0 +1,108 @@
+# Command Cheatsheet
+
+Use `mkt --help` and `mkt <command> --help` for the live command surface. This
+cheatsheet is organized by intent.
+
+## Inspect Markdown
+
+```bash
+mkt parse file.md --format json
+mkt parse file.md --format tree
+mkt ast show file.md --format yaml
+mkt ast stats file.md
+mkt metrics file.md
+```
+
+## Validate Structure
+
+```bash
+mkt validate file.md --schema schema.md
+mkt schema validate schema.md
+mkt contract validate contract.md
+mkt contract check file.md --contract contract.md
+mkt contract form-state file.md --contract contract.md --context context.yaml
+```
+
+## Query And Extract
+
+```bash
+mkt query file.md 'sections[heading=Decision]'
+mkt extract file.md 'sections[heading=Decision]' --format text
+mkt query file.md '$.sections[*].heading.text' --engine jsonpath
+```
+
+## Transform And Reuse
+
+```bash
+mkt transform file.md --set status=ready
+mkt compose one.md two.md --title Combined
+mkt include file.md --base-dir .
+mkt ref resolve context.md 'std:clauses.md#payment-terms' --root examples/references
+mkt process file.md --root .
+```
+
+## Split And Literate Workflows
+
+```bash
+mkt explode file.md --output-dir parts
+mkt implode parts --output rebuilt.md
+mkt tangle examples/literate/app.md --output-dir build
+mkt weave examples/literate/app.md --output woven.md
+```
+
+## Generate Markdown
+
+```bash
+mkt template inspect template.md
+mkt template render template.md --data data.yaml
+mkt generate stub --contract contract.md --include-optional
+mkt generate rules generation.md --output-dir out
+mkt function list
+mkt function check file.md
+mkt function render file.md
+```
+
+## Index, Search, And Refresh
+
+```bash
+mkt cache init --root .
+mkt cache build docs --root .
+mkt cache status docs --root .
+mkt cache index docs --root .
+mkt cache query 'sections[heading=Decision]' --root .
+mkt search latency --root . --limit 10
+mkt backend refresh-plan docs --root .
+```
+
+## Policy-Aware Access
+
+```bash
+mkt policy check public-agent read object-id --policy policy.yaml
+mkt policy subject claims.yaml --policy-map policy-map.yaml
+mkt policy resource-manifest manifest.yaml
+mkt search internal --root . --policy policy.yaml --subject internal-agent
+```
+
+## Workflows And Context Packages
+
+```bash
+mkt workflow inspect workflow.md
+mkt workflow plan workflow.md --output-dir out
+mkt workflow run workflow.md --output-dir out
+mkt context pack query --source file.md --max-items 5
+mkt context activate package-id
+mkt context explain package-id
+mkt context refresh package-id
+mkt context list
+```
+
+## Discovery And Docs
+
+```bash
+mkt completion bash --instructions
+mkt extension list
+mkt extension inspect backend.local-sqlite
+mkt extension commands
+mkt docs cli --output docs/cli-reference.md
+mkt docs api --output docs/api-reference.md
+```

docs/examples-index.md

@@ -0,0 +1,50 @@
+# Examples Index
+
+This index maps example files to practical usecases and useful commands.
+
+## Contracts And Diagnostics
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/contracts/adr.contract.md`, `examples/documents/adr-valid.md` | ADR contract validation | `mkt contract check examples/documents/adr-valid.md --contract examples/contracts/adr.contract.md` |
+| `examples/contracts/business-letter.contract.md`, `examples/documents/business-letter-valid.md` | Form-like business document validation | `mkt contract form-state examples/documents/business-letter-valid.md --contract examples/contracts/business-letter.contract.md --context examples/runtime/business-letter.context.yaml` |
+| `examples/contracts/prd-frs.contract.md`, `examples/documents/prd-frs-valid.md` | Larger product/specification contract | `mkt contract check examples/documents/prd-frs-valid.md --contract examples/contracts/prd-frs.contract.md` |
+| `examples/diagnostics/*.expected-diagnostics.md` | Expected failure explanations | Compare with `mkt contract check ... --format text` |
+
+## Query, References, And Processors
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/references/context.md` | Namespace, region, fence, and section references | `mkt ref resolve examples/references/context.md 'std:clauses.md#payment-terms' --root examples/references` |
+| `examples/references/standard/clauses.md` | Referenced reusable content | Use with `mkt ref resolve` or `mkt process` |
+| `examples/migration/legacy-path-include.md` | Migration-style include handling | `mkt include examples/migration/legacy-path-include.md --base-dir examples/migration` |
+| `examples/functions/basic-functions.md` | Deterministic document functions | `mkt function render examples/functions/basic-functions.md` |
+
+## Templates, Generation, And Workflows
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/templates/adr-summary.template.md`, `examples/templates/adr-summary.data.yaml` | Data-bound Markdown template | `mkt template render examples/templates/adr-summary.template.md --data examples/templates/adr-summary.data.yaml` |
+| `examples/templates/adr-summary.generation.md` | Rule-based generation plan | `mkt generate rules examples/templates/adr-summary.generation.md --output-dir /tmp/markitect-generated` |
+| `examples/workflows/source-snippets.workflow.md` | Extract snippets from Markdown sources | `mkt workflow plan examples/workflows/source-snippets.workflow.md --output-dir /tmp/markitect-workflow` |
+| `examples/workflows/adr-release-notes.workflow.md` | ADR release notes workflow | `mkt workflow plan examples/workflows/adr-release-notes.workflow.md --output-dir /tmp/markitect-workflow` |
+| `examples/workflows/assisted-review.workflow.md` | Assisted-generation boundary shape | Inspect with `mkt workflow inspect` |
+
+## Cache, Backend, Policy, And Context
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/backends/local-sqlite-backend.md` | Backend manifest inspection | `mkt backend inspect local-sqlite --path examples/backends/local-sqlite-backend.md` |
+| `examples/backend-state/snapshot-state.yaml` | Refresh planning fixture | `mkt backend refresh-plan examples/documents --state examples/backend-state/snapshot-state.yaml --root .` |
+| `examples/policy/local-label-policy.yaml` | Local policy gateway | `mkt policy check public-agent read note --policy examples/policy/local-label-policy.yaml --label public` |
+| `examples/policy/enterprise-policy-map.yaml` | Enterprise IAM mapping fixture | `mkt policy subject examples/policy/netkingdom-claims.yaml --policy-map examples/policy/enterprise-policy-map.yaml` |
+| `examples/memory/workplan-context.manifest.yaml` | Context package manifest | `mkt context pack examples/memory/workplan-context.manifest.yaml --root . --no-save` |
+
+## Literate And Migration
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/literate/app.md` | Weave/tangle style code/document workflow | `mkt tangle examples/literate/app.md --output-dir /tmp/markitect-tangle` |
+| `examples/migration/legacy-explode-source.md` | Reversible section splitting | `mkt explode examples/migration/legacy-explode-source.md --output-dir /tmp/markitect-parts` |
+| `examples/migration/legacy-literate.md` | Legacy literate migration sample | `mkt weave examples/migration/legacy-literate.md` |
+| `examples/classes/prd-classes.yaml` | Content class composition | `mkt class resolve examples/classes/prd-classes.yaml product-prd` |

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.

docs/performance-notes.md

@@ -0,0 +1,60 @@
+# Performance Notes
+
+Markitect is designed to remain useful without persistent services. The current
+performance posture is therefore local-first:
+
+- parse individual Markdown files directly for one-off use
+- build a local SQLite index for repeated corpus operations
+- use refresh planning to avoid unnecessary parse/index work
+- keep policy filtering and context package creation deterministic
+
+## Current Smoke Coverage
+
+`tests/test_practical_usecases_e2e.py` includes a large-corpus smoke test that
+creates 120 synthetic Markdown files, indexes them locally, and runs an FTS
+search.
+
+The thresholds are intentionally generous:
+
+- local cache/index build: under 30 seconds
+- local indexed search: under 5 seconds
+
+These are not benchmark claims. They are regression guards to catch accidental
+algorithmic or IO mistakes while keeping the test portable.
+
+## Practical Guidance
+
+For one file:
+
+```bash
+mkt parse file.md
+mkt query file.md 'sections[heading=Decision]'
+```
+
+For a directory you will query repeatedly:
+
+```bash
+mkt cache index docs --root .
+mkt search keyword --root .
+mkt cache query 'sections[heading=Decision]' --root .
+```
+
+Before refreshing derived work:
+
+```bash
+mkt backend refresh-plan docs --root . --verify-hashes
+```
+
+## Future Measurement
+
+If performance becomes a release gate, add a separate benchmark suite instead
+of tightening normal E2E tests. Good benchmark dimensions would be:
+
+- number of documents
+- total bytes
+- heading/section density
+- frontmatter size
+- number of reference/include relationships
+- policy labels per document
+- index rebuild versus incremental refresh
+- context package item and token budgets

docs/workplan-planning-map.md

@@ -41,7 +41,7 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0014` | complete | done | `MKTT-WP-0009` | Markitect-side enterprise IAM access-control integration is complete: NetKingdom/key-cape-compatible identity claims, flex-auth resource/policy contract, directory group resolution fixtures, decision-log sink, workflow declarations, CLI commands, and external PDP request examples. |
 | `MKTT-WP-0012` | complete | done | `MKTT-WP-0004`, `MKTT-WP-0010`, `MKTT-WP-0011` | Document function layer is complete: deterministic Markdown-native function descriptors, registry, inline/fenced syntax, pipelines, context bindings, CLI, docs, examples, diagnostics, provenance, and extension descriptor. |
 | `MKTT-WP-0008` | complete | done | `MKTT-WP-0006`, `MKTT-WP-0007`, `MKTT-WP-0009` | Agent working-memory context cache is complete: context package schema, local registry, package creation from queries/search/manifests, deterministic summaries, namespaces, activation/deactivation/refresh/explain lifecycle, policy re-checks, CLI, docs, and examples. |
-| `MKTT-WP-0017` | P1 | active | `MKTT-WP-0003`, `MKTT-WP-0013` | Current polish/adoption track: CLI/API completeness, shell completion, generated command/API docs, usecase relevance matrix, E2E fixture planning, accessibility, and test/performance iteration before more advanced feature work. |
+| `MKTT-WP-0017` | complete | done | `MKTT-WP-0003`, `MKTT-WP-0013` | CLI/API polish and practical adoption track is complete: shell completion, extension discovery, generated CLI/API docs, usecase relevance matrix, E2E fixture matrix, large-corpus smoke coverage, first-use docs, examples index, and command cheat sheet. |
 | `MKTT-WP-0015` | P2 | todo | `MKTT-WP-0010`, `MKTT-WP-0011`, `MKTT-WP-0012` | Future render and document-function extensions: typed values, richer syntax, document-local reusable functions, Quarkdown/export adapters, render-aware references, assets, and permission sandboxing. Defer unless publishing/export pressure becomes current. |
 | `MKTT-WP-0016` | P2 | todo | `MKTT-WP-0008`, `MKTT-WP-0007`, `MKTT-WP-0009`, `MKTT-WP-0013` | Follow-on agentic memory architecture: reasoning decision graphs, conversational paths, long-term knowledge graphs, memory service blueprints/profiles, graph-to-context-package compilation, and adapter boundaries. |