markitect-tool/workplans/MKTT-WP-0017-cli-api-polish-and-practical-adoption.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0017	workplan	CLI/API Polish And Practical Adoption	markitect	active	markitect-tool	markitect	P1	40	MKTT-WP-0003 MKTT-WP-0013	MKTT-WP-0004 MKTT-WP-0007 MKTT-WP-0008 MKTT-WP-0010 MKTT-WP-0011	2026-05-04	2026-05-04	077bc50c-360b-425a-a1ad-fd961f819422

MKTT-WP-0017: CLI/API Polish And Practical Adoption

Purpose

Polish markitect-tool from a broad implementation toolkit into something that is easy to discover, use, document, test, and adopt in practical Markdown pipelines.

This workplan intentionally pauses advanced future architecture work and focuses on the public surface:

• CLI completeness and consistency
• shell completion and Unix-style generated command documentation
• public API completeness and generated API documentation
• CLI/API alignment with the extension architecture
• usecase-driven E2E testing
• accessibility for practical first use

Decisions

• Treat every implemented architecture capability as something that should be discoverable through CLI, API, docs, and extension descriptors.
• Keep generated docs deterministic and local-first.
• Use web-researched practical usecases as adoption and E2E-test anchors.
• Prefer improving command/API discoverability before adding more advanced features.

P17.1 - Audit CLI and API surface completeness

id: MKTT-WP-0017-T001
status: done
priority: high
state_hub_task_id: "1827fec2-3c64-4dd0-9b24-e6a7c3a19912"

Review all implemented modules, built-in extensions, and docs. Identify missing CLI accesspoints, missing public API exports, and mismatches between extension descriptors and real commands.

Initial implementation adds:

• mkt completion
• mkt extension list
• mkt extension inspect
• mkt extension commands
• mkt docs cli
• mkt docs api
• top-level API exports for newer query, backend, extension, schema, and policy surfaces

Output: implementation, tests, and an updated audit note if gaps remain.

P17.2 - Provide shell completion and Unix-style command docs

id: MKTT-WP-0017-T002
status: done
priority: high
state_hub_task_id: "052b9684-cc23-4215-926e-bc498fe10f4f"

Expose Bash, Zsh, and Fish completion scripts through the CLI and generate a Markdown command reference from the live Click tree.

Output: CLI command, generated docs/cli-reference.md, README installation notes, and tests.

P17.3 - Provide generated API documentation

id: MKTT-WP-0017-T003
status: done
priority: high
state_hub_task_id: "8874078a-e2f4-4a4e-a2d0-a7cbd5d62816"

Generate a compact public API reference from markitect_tool.__all__ and make pdoc available as an optional richer documentation path.

Output: CLI command, generated docs/api-reference.md, optional docs extra, README notes, and tests.

P17.4 - Compile practical usecases and relevance expectations

id: MKTT-WP-0017-T004
status: done
priority: high
state_hub_task_id: "23fffff4-a1f0-498c-b4d7-00241d0bb29d"

Revisit INTENT.md, PRD, FRS, examples, and docs. Use web research to define a practical usecase matrix with relevance expectations and adoption signals.

Output: docs/practical-usecase-relevance.md and links from intent/README.

P17.5 - Build E2E fixture matrix

id: MKTT-WP-0017-T005
status: in_progress
priority: high
state_hub_task_id: "1159ec82-00e6-45cd-8a2c-e61ae03e758a"

Create E2E tests for the practical usecases with small, typical, and large variations where meaningful.

Required coverage:

• parse/AST/metrics
• schema and contract checks
• query/extract and indexed search
• transform/compose/include/references/processors
• templates/generation/functions
• workflow inspect/plan/run
• cache/index/refresh plans
• policy-aware query/search
• literate weave/tangle
• explode/implode
• runtime form-state
• context packages
• extension catalog and generated docs

Output: deterministic tests and fixtures with no network dependency.

Initial coverage has been added for:

• small, typical, and large synthetic corpus parse/query/cache/search/context package flow
• example-backed contract, template, function, workflow, reference, processor, policy, literate tangle, and explode/implode flows

Remaining work: expand the matrix into explicit small/typical/large variants for every high-relevance workflow and add performance assertions where they are stable.

P17.6 - Run coverage and performance iteration

id: MKTT-WP-0017-T006
status: todo
priority: high
state_hub_task_id: "8dd5afe5-cefa-4388-bf4c-a975ba5c77c3"

Run full tests repeatedly, add coverage instrumentation if needed, and fix bugs or performance issues exposed by the E2E matrix.

Output: passing test suite, documented coverage gaps, and targeted performance notes for large synthetic corpora.

P17.7 - Improve first-use accessibility

id: MKTT-WP-0017-T007
status: todo
priority: medium
state_hub_task_id: "590af805-0cc0-4585-b85f-9e95679afa77"

Make the first useful experience obvious.

Possible improvements:

• concise README quickstart with common workflows
• generated examples index
• command cheat sheet
• install/completion instructions
• clearer diagnostics examples
• mkt extension discovery guidance
• optional docs generation workflow using pdoc

Output: README/docs/examples polish and tests where executable.

Exit Criteria

• Every implemented subsystem has CLI access, public API access, docs, examples, and tests or a documented reason for omission.
• Shell completion works for Bash, Zsh, and Fish through mkt completion.
• docs/cli-reference.md and docs/api-reference.md can be regenerated from the live implementation.
• Practical usecases are documented with relevance expectations and E2E coverage targets.
• E2E tests cover small, typical, and large variations for the important workflows.
• Full test suite passes.