[v1.0] Repair generated API and Typer adapter contract documentation

[codeforester]

Goal

Make the published reference describe runtime behavior instead of Python implementation artifacts or impossible call sequences.

Background

The API generator calls inspect.getdoc(value) for constants and typing helpers:

base-cli/scripts/generate_api_reference.py

Lines 32 to 61 in 8a93d22

	def _kind(value: Any) -> str:
	if inspect.ismodule(value):
	return "module"
	if inspect.isclass(value):
	return "class"
	if inspect.isfunction(value) or inspect.ismethod(value):
	return "function"
	if isinstance(value, type):
	return "class"
	return "constant/type"
	def _signature(name: str, value: Any) -> str:
	try:
	if inspect.isclass(value) or inspect.isfunction(value) or inspect.ismethod(value):
	signature = str(inspect.signature(value))
	# Default callback reprs contain process-specific memory addresses.
	signature = re.sub(r" at 0x[0-9a-fA-F]+", "", signature)
	return f"`{name}{signature}`"
	except (TypeError, ValueError):
	pass
	return "(value is not callable)"
	def _description(value: Any) -> str:
	doc = inspect.getdoc(value)
	if not doc:
	return "Public facade symbol; see the linked contract and source annotations for details."
	first_paragraph = doc.split("\n\n", 1)[0].replace("\n", " ").strip()
	return first_paragraph

. Runtime strings, mappings, and integers therefore inherit built-in constructor documentation. For example, version and schema constants are described with str behavior, and RECORD_SCHEMAS receives dict behavior, despite #194 requiring behavior, errors, and examples for every export.

The Typer guide also says calling TyperAdapter.attach() again refreshes the cached command:

base-cli/docs/typer-adapter.md

Lines 61 to 71 in 8a93d22

	`TyperAdapter` is available when the generated command needs to be retained:
	```python
	adapter = base_cli.TyperAdapter(cli)
	command = adapter.attach(name="example")
	```
	`adapter.command` exposes the cached Click command returned by the most recent
	`attach()` call. Reuse that object when the application needs to inspect or
	pass the generated command to another integration boundary; calling
	`attach()` again refreshes the cached command.

. The implementation rejects a second attachment when arguments differ, so the documented refresh workflow raises TypeError.

Scope

• Add symbol-owned descriptions for constants/type aliases instead of introspecting their runtime value types.
• State the exact idempotency/mutation contract for TyperAdapter.attach().
• Add semantic documentation checks beyond heading inventory.

Acceptance Criteria

• Every constant/type alias has a meaningful framework-specific description and representative value/example.
• The reference no longer publishes built-in str, int, or dict constructor prose as behavior.
• Typer docs and runtime agree for repeated identical and changed attachment calls.
• CI contains representative semantic assertions for generated constant and adapter documentation.
• Public API stability and migration guidance are updated if runtime behavior changes.

Validation

Regenerate/build docs strictly and run API-stability, Typer matrix, and link checks.

Non-Goals

Do not expose private modules or expand the facade to satisfy the generator.

Project Fields

• Status: Backlog
• Priority: P2
• Area: Docs
• Initiative: Adoption Polish
• Size: S

Ownership

• Assignee: @codeforester