docs: fix spec contradictions, stale references, and import path inconsistencies

- ai-enhancement.md: clarify metadata.ai_guidance vs metadata["display"]["guidance"]
  relationship; document Enhancer sync (Python) vs async (TypeScript) as deliberate
- convention-scanning.md: document ConventionScanner extends BaseScanner, Python-only
- getting-started.md: replace --ai-enhance CLI flag with programmatic AIEnhancer usage;
  fix dead CHANGELOG.md link
- openapi.md: unify TypeScript import path to "apcore-toolkit"
- overview.md: add schema enrichment to Formatting description

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tercel

docs/ai-enhancement.md

@@ -7,7 +7,7 @@ This document specifies how `apcore-toolkit` fills metadata gaps that static ana
 The toolkit's primary mission is to make existing code "AI-Perceivable". While static analysis (regex, AST, type hints) is efficient, it often fails to:
 
 - Generate meaningful `description` and `documentation` for legacy code with no docstrings.
-- Create effective guidance (stored in `metadata.ai_guidance`) for complex error handling paths.
+- Create effective guidance for complex error handling paths. (The scanner stores raw guidance in `metadata.ai_guidance`; `DisplayResolver` later resolves it into `metadata["display"]["guidance"]` for surface-specific consumption — see [Display Overlay](features/display-overlay.md).)
 - Infer `input_schema` for functions using `*args` or `**kwargs`.
 - Determine behavioral `annotations` (e.g., is this function destructive?) from code logic.
 
@@ -67,6 +67,9 @@ The toolkit exports a generic `Enhancer` protocol that any enhancement implement
     }
     ```
 
+!!! note "Sync vs Async"
+    The Python `Enhancer` protocol is synchronous (`list[ScannedModule]`) while the TypeScript interface is asynchronous (`Promise<ScannedModule[]>`). This is a deliberate language-convention choice: TypeScript enhancement calls (HTTP to SLM endpoints) are inherently async. Python implementations may use either sync or async internally; the protocol defines the sync signature for broader compatibility.
+
 ### Contract
 
 - The enhancer receives modules **after** static scanning is complete.

docs/features/convention-scanning.md

@@ -15,6 +15,9 @@ This is the lowest-friction path to creating apcore modules: drop a `.py` file i
 **Class**: `apcore_toolkit.convention_scanner.ConventionScanner`
 **Module**: `apcore_toolkit/convention_scanner.py`
 
+!!! note "Relationship to BaseScanner"
+    `ConventionScanner` **extends** `BaseScanner` and inherits its shared utilities (`filter_modules`, `deduplicate_ids`, `infer_annotations_from_method`, `extract_docstring`). Its `scan()` method accepts a positional `commands_dir` parameter (plus keyword-only `include`/`exclude`) rather than the generic `**kwargs` of the abstract base — this is valid because `BaseScanner.scan()` declares `**kwargs` to allow subclass-specific signatures. Convention scanning is currently **Python-only** because it relies on Python's `importlib` to dynamically load `.py` files.
+
 ### Method Signature
 
 ```python

docs/features/openapi.md

@@ -51,8 +51,7 @@ This produces the flat `input_schema` required by the `ScannedModule`.
 === "TypeScript"
 
     ```typescript
-    import { extractInputSchema, extractOutputSchema } from "apcore-toolkit/openapi";
-    import { ScannedModule } from "apcore-toolkit";
+    import { extractInputSchema, extractOutputSchema, ScannedModule } from "apcore-toolkit";
 
     // Load an OpenAPI spec
     const openapiSpec = { ... };

docs/features/overview.md

@@ -10,7 +10,7 @@
 | **[OpenAPI Integration](openapi.md)** | Extract JSON Schemas directly from OpenAPI operation objects. |
 | **[Schema Utilities](pydantic.md)** | Flatten complex models (Pydantic / Zod) for easier AI interaction. |
 | **[Output Writers](output-writers.md)** | Export metadata to YAML bindings, source code wrappers, or direct Registry registration — with optional output verification. |
-| **[Formatting](formatting.md)** | Convert data structures into beautiful, human-readable Markdown. |
+| **[Formatting](formatting.md)** | Convert data structures into Markdown and enrich JSON Schema descriptions from docstrings. |
 | **[AI Enhancement](../ai-enhancement.md)** | Pluggable `Enhancer` protocol with built-in `AIEnhancer` for local SLMs; [apcore-refinery](https://github.com/aiperceivable/apcore-refinery) recommended for production. |
 | **[Display Overlay](display-overlay.md)** | Sparse `binding.yaml` overlay that resolves surface-facing alias, description, guidance, and tags into `metadata["display"]` for CLI, MCP, and A2A surfaces (§5.13). |
 | **[Convention Scanning](convention-scanning.md)** | Scan a `commands/` directory of plain Python files for public functions, inferring schemas from type annotations -- zero decorators, zero imports (§5.14). |

docs/getting-started.md

@@ -262,7 +262,30 @@ The toolkit includes a built-in `AIEnhancer` that calls any OpenAI-compatible lo
    ```bash
    export APCORE_AI_ENABLED=true
    ```
-3. **Run your scanner** with `--ai-enhance`: Missing descriptions, annotations, and schemas will be inferred automatically.
+3. **Use AIEnhancer programmatically** after scanning:
+
+=== "Python"
+
+    ```python
+    from apcore_toolkit import AIEnhancer
+
+    if AIEnhancer.is_enabled():
+        enhancer = AIEnhancer()
+        modules = enhancer.enhance(modules)
+    ```
+
+=== "TypeScript"
+
+    ```typescript
+    import { AIEnhancer } from "apcore-toolkit";
+
+    if (AIEnhancer.isEnabled()) {
+      const enhancer = new AIEnhancer();
+      modules = await enhancer.enhance(modules);
+    }
+    ```
+
+Missing descriptions, annotations, and schemas will be inferred automatically.
 
 For production use, we recommend **[apcore-refinery](https://github.com/aiperceivable/apcore-refinery)** which provides better prompts, model flexibility, and CI integration:
 
@@ -278,5 +301,5 @@ See the [AI Enhancement Guide](ai-enhancement.md) for the full `Enhancer` protoc
 
 - **[Features Overview](features/overview.md)** — Deep dive into all toolkit capabilities.
 - **[AI Enhancement Guide](ai-enhancement.md)** — Enhancer protocol, built-in AIEnhancer, and apcore-refinery.
-- **[Changelog](../CHANGELOG.md)** — See what's new in the latest release.
+- **[Changelog](https://github.com/aiperceivable/apcore-toolkit/releases)** — See what's new in the latest release.
 - **[apcore Documentation](https://aiperceivable.github.io/apcore/)** — Learn more about the core framework.