# Practical Usecase Relevance

This document translates the project intent, PRD, FRS, and current
implementation into practical adoption usecases for `markitect-tool`.

The relevance expectations are based on the local product scope plus a light web
research pass across Markdown documentation ecosystems, docs-as-code practice,
RAG/agent context tooling, policy-as-code systems, and Markdown publishing
systems.

## Research Signals

- CommonMark exists because Markdown needed a strongly defined, compatible
  specification across many implementations: https://commonmark.org/
- GitLab documents large handbook and product-doc workflows in Markdown, with
  linting/style enforcement in the pipeline:
  https://handbook.gitlab.com/docs/markdown-guide/ and
  https://docs.gitlab.com/development/documentation/styleguide/
- MkDocs positions itself directly as project documentation with Markdown and
  uses Markdown files plus YAML configuration:
  https://www.mkdocs.org/
- Docusaurus uses Markdown/MDX as its main authoring format and highlights the
  tension between CommonMark compatibility and richer MDX component behavior:
  https://docusaurus.io/docs/3.2.1/markdown-features
- LangChain and Semantic Kernel both model RAG around loading, splitting,
  storing, retrieving, and injecting text context:
  https://docs.langchain.com/oss/python/langchain/rag and
  https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/agent-rag
- OPA and OpenFGA show that policy and authorization are commonly externalized
  into dedicated engines, which supports Markitect's adapter-first boundary:
  https://www.openpolicyagent.org/docs and https://openfga.dev/docs/fga
- Quarkdown demonstrates current interest in Markdown extended with functions,
  scripting, and richer publishing semantics:
  https://www.quarkdown.net/about
- Click already supports shell completion for Bash, Zsh, and Fish when exposed
  through an installed entry point:
  https://click.palletsprojects.com/en/stable/shell-completion/
- pdoc and Sphinx show common expectations for automatic Python API
  documentation from public APIs and docstrings:
  https://pdoc.dev/ and
  https://www.sphinx-doc.org/en/master/usage/extensions/apidoc.html

## Usecase Matrix

| Usecase | Relevance | Why It Matters | Current Support | E2E Variations |
| --- | --- | --- | --- | --- |
| Parse Markdown into structured ASTs | Foundational | Every higher-level workflow needs stable structure and source spans. | `mkt parse`, `mkt ast`, API parser primitives | Small single note, typical ADR/PRD, large multi-section document |
| Contract-check business documents | High | Teams need predictable structure, assertions, field validation, and diagnostics. | `mkt contract validate/check/form-state`, contract APIs | Small concept note, typical ADR/business letter, large PRD/FRS bundle |
| Query and extract reusable content | High | Docs-as-code and agent/RAG workflows need selectors over source Markdown. | `mkt query`, `mkt extract`, JSONPath, indexed query | Small file query, typical docs directory, large cached corpus |
| Transform, compose, include, transclude | High | Real document pipelines need deterministic reuse without manual copy/paste. | `mkt transform`, `compose`, `include`, references, processors | Small include, typical multi-source review, large composed handbook segment |
| Generate documents from templates/contracts | High | Practical adoption depends on producing useful Markdown, not only checking it. | `mkt template`, `mkt generate`, document functions | Small template, typical release notes, large generated document pack |
| Declarative Markdown workflows | High | Business usecases need repeatable pipelines with intent, inputs, outputs, and diagnostics. | `mkt workflow inspect/plan/run` | Small source-snippet workflow, typical ADR release notes, large multi-input pipeline |
| Local indexing, search, and incremental refresh | High | Large corpora require speed, change detection, and retrieval without reparsing everything. | `mkt cache`, `mkt backend refresh-plan`, `mkt search` | Small two-file index, typical docs tree, large synthetic corpus |
| Policy-aware knowledge access | Medium-high | Enterprise use needs safe filtering and explainable denial without making Markitect the IAM system. | `mkt policy`, policy-filtered `search`, policy-filtered `cache query` | Public/private notes, typical trust-zone docs, large labelled corpus |
| Literate weave/tangle workflows | Medium-high | Knuth-style authoring and modern docs-as-code both benefit from code/document roundtrips. | `mkt tangle`, `mkt weave` | Small code chunk, typical app skeleton, large multi-file tangle |
| Explode/implode document sections | Medium-high | Human editing and review often need splitting documents while preserving roundtrip integrity. | `mkt explode`, `mkt implode` | Small flat split, typical hierarchical doc, large section tree |
| Runtime forms and dynamic context prefill | Medium-high | Structured documents often originate as form-like workflows with validation and prefills. | `mkt contract form-state`, runtime context APIs | Small static form, typical prefilled letter, large dynamic contract |
| Agent working-memory context packages | Medium-high | Agents need bounded, inspectable context payloads with provenance and policy rechecks. | `mkt context pack/activate/explain/refresh/list` | Small source package, typical indexed package, large budget-limited package |
| Document function layer | Medium | Quarkdown-like function layers make Markdown more expressive while keeping deterministic boundaries. | `mkt function list/check/render` | Small inline function, typical function fence, large generated function document |
| Internal extension framework | Medium | Future growth requires extension isolation, descriptors, docs, safety, and CLI/API visibility. | `mkt extension list/inspect/commands`, extension APIs | Built-in registry, docs descriptor, future optional adapter descriptor |
| Generated CLI/API documentation | Medium | Accessibility improves when users can discover the live surface without reading code. | `mkt docs cli`, `mkt docs api`, generated docs files | Console output, committed Markdown, packaging docs build |

## Coverage Expectations

The adoption polish work should treat these usecases as the public contract:

- Each usecase should have at least one API test and one CLI test.
- Each high-relevance usecase should have small, typical, and large E2E
  fixtures.
- Large fixtures should be synthetic enough to stay fast but big enough to catch
  obvious performance regressions.
- E2E tests should assert useful behavior, diagnostics, and output shape, not
  only zero exit codes.
- Optional adapters should be tested through stable local fakes and must not
  require network or live LLM calls.

## Accessibility Expectations

Markitect becomes more accessible when:

- users can install one command and get `--help`, tab completion, and generated
  command docs
- every architecture capability is discoverable through `mkt extension`
- API docs are generated from the public API and kept close to the source
- examples map directly to usecases and can be copied into local experiments
- diagnostics use stable codes, source locations, and concise remediation hints
- defaults support practical single-file work before asking users to configure a
  full project