Complete CommandKit consumer documentation

docs/internal/overview.md

@@ -0,0 +1,36 @@
+# 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 package imports `internal/cobra` to bridge its command declarations and
+invocations to Cobra parsing and routing. Application callbacks, output streams,
+context, and supported error identity cross that bridge through the root's typed
+contracts.
+
+## `internal/cobra`
+
+This package owns the Cobra-specific command tree and argument/flag parsing
+adapter. 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 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.