markitect-tool/docs/practical-usecase-relevance.md

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