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

---
id: MKTT-WP-0017
type: workplan
title: "CLI/API Polish And Practical Adoption"
domain: markitect
status: active
owner: markitect-tool
topic_slug: markitect
planning_priority: P1
planning_order: 40
depends_on_workplans:
  - MKTT-WP-0003
  - MKTT-WP-0013
related_workplans:
  - MKTT-WP-0004
  - MKTT-WP-0007
  - MKTT-WP-0008
  - MKTT-WP-0010
  - MKTT-WP-0011
created: "2026-05-04"
updated: "2026-05-04"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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.