commandkit/docs/internal/overview.md

# Internal package overview

CommandKit ships one public package, `commandkit`, and one internal package,
`internal/cobra`. This inventory describes the current implementation; the
[architecture policy](../policy/architecture.md) owns normative boundaries and
[ADR 0003](../adr/0003-public-facade.md) records the public package boundary.

## `commandkit`

The root package declares the public API and owns the instance registry, typed
command input preparation, invocation coordination, standard handlers, and
provider adapters. Configuration reports adapt ConfigKit's public records and
writers. PromptKit scope and definition handlers use PromptKit's public
inspection methods and map their results to CommandKit-owned reports.

The root lowers registered command metadata into the internal adapter's neutral
bridge. The adapter returns raw parsed values and neutral syntax-failure data;
the root prepares typed input, invokes application/standard handlers, and
coordinates outcomes and diagnostic delivery. Application callbacks and their
supported error identity remain in the root's typed contracts rather than
crossing the backend bridge. Context and streams are passed to the adapter for
its parsing and help operations.

## `internal/cobra`

This package owns the Cobra-specific command tree, argument/flag parsing,
and help rendering. It translates neutral command metadata and parsed values into a bridge
result consumed by the root package. It does not import `commandkit` and does not
own registry policy, public command declarations, provider loading, or standard
inspection report rendering.

## External implementation boundaries

ConfigKit owns typed configuration loading, source history, validation,
resolution, and path explanations. PromptKit owns captured engine
configuration, prompt definitions, profile inheritance, and named inspections.
CommandKit depends on their public module APIs and does not maintain parallel
schemas. Cobra and pflag are confined behind the internal adapter; YAML report
encoding is performed by the root package.