refactor(docs): code analysis engine

changes:
  - file: cli.py
    area: cli
    added: [_run_check, _run_diff, check, diff]
  - file: _registry_adapters.py
    area: docs
    added: [ContributingAdapter, GettingStartedAdapter, ConfigDocsAdapter]
    modified: [run]
  - file: config_docs_gen.py
    area: config
    added: [ConfigDocsGenerator, generate, _render_section, _render_example, __init__]
  - file: contributing_gen.py
    area: docs
    added: [generate, _render_setup, _render_code_style, _render_testing, __init__, _render_pull_request, +3 more]
  - file: getting_started_gen.py
    area: docs
    added: [generate, _render_next_steps, _render_installation, __init__, _render_prerequisites, _render_first_usage, +2 more]
  - file: test_cli.py
    area: cli
    new_tests: 4
    modified: [TestCLI]
  - file: test_generators.py
    area: test
    added: [TestGettingStartedGenerator, TestContributingGenerator, TestConfigDocsGenerator]
    new_tests: 10
  - file: test_registry.py
    area: test
    added: [TestBaseGenerator, _AlwaysGenerator, TestGeneratorRegistry, should_run, TestAdapters, _DummyGenerator, +6 more]
    new_tests: 14

testing:
  new_tests: 28
  scenarios:
    - diff_runs
    - check_help
    - diff_help
    - check_runs
    - contains_testing
    - contains_next_steps
    - contains_example_yaml
    - contains_nested_sections
    - contains_prerequisites
    - contains_top_level_options
    # +18 more

dependencies:
  flow: "basic_usage→registry, _registry_adapters→getting_started_gen, entry_points→code2docs, cli→config"
  - cli.py -> config.py
  - cli.py -> registry.py
  - basic_usage.py -> registry.py
  - entry_points.py -> registry.py
  - entry_points.py -> code2docs.py
  - _registry_adapters.py -> getting_started_gen.py

stats:
  lines: "+4620/-0 (net +4620)"
  files: 80
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-03-07
+
+### Docs
+- Update code2docs/README.md
+- Update code2docs/docs/api-changelog.md
+- Update code2docs/docs/api/index.md
+- Update code2docs/docs/api/module___main__.md
+- Update code2docs/docs/api/module_analyzers.md
+- Update code2docs/docs/api/module_analyzers_dependency_scanner.md
+- Update code2docs/docs/api/module_analyzers_docstring_extractor.md
+- Update code2docs/docs/api/module_analyzers_endpoint_detector.md
+- Update code2docs/docs/api/module_analyzers_project_scanner.md
+- Update code2docs/docs/api/module_base.md
+- ... and 58 more files
+
+### Test
+- Update tests/test_cli.py
+- Update tests/test_generators.py
+- Update tests/test_registry.py
+
+### Other
+- Update code2docs/cli.py
+- Update code2docs/examples/basic_usage.py
+- Update code2docs/examples/class_examples.py
+- Update code2docs/examples/entry_points.py
+- Update code2docs/generators/__init__.py
+- Update code2docs/generators/_registry_adapters.py
+- Update code2docs/generators/config_docs_gen.py
+- Update code2docs/generators/contributing_gen.py
+- Update code2docs/generators/getting_started_gen.py
+
 ## [0.2.2] - 2026-03-07
 
 ### Other

README.md

@@ -1,6 +1,6 @@
 # code2docs
 
-![version](https://img.shields.io/badge/version-0.2.2-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
+![version](https://img.shields.io/badge/version-0.2.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![docs](https://img.shields.io/badge/docs-auto--generated-blueviolet)
 
 > Auto-generate and sync project documentation from source code analysis.
 
@@ -140,7 +140,7 @@ code2docs can update only specific sections of an existing README using markers:
 ```markdown
 <!-- code2docs:start --># code2docs
 
-![version](https://img.shields.io/badge/version-0.2.2-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-153-green)
+![version](https://img.shields.io/badge/version-0.2.3-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-153-green)
 > **153** functions | **30** classes | **28** files | CC̄ = 0.0
 
 ## Installation

VERSION

@@ -1 +1 @@
-0.2.2
+0.2.3

code2docs/README.md

@@ -0,0 +1,118 @@
+<!-- code2docs:start --># code2docs
+
+![version](https://img.shields.io/badge/version-0.1.0-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-185-green)
+> **185** functions | **42** classes | **31** files | CC̄ = 3.8
+
+## Installation
+
+```bash
+pip install .
+```
+
+
+## Quick Start
+
+```python
+# Entry point: registry.GeneratorRegistry.__init__
+# Entry point: registry.GeneratorRegistry.add
+# Entry point: registry.GeneratorRegistry.run_all
+```
+
+## API Overview
+
+### Classes
+
+- **`GeneratorRegistry`** — Registry of documentation generators.
+- **`Updater`** — Apply selective documentation updates based on detected changes.
+- **`ChangeInfo`** — Describes a detected change.
+- **`Differ`** — Detect changes between current source and previous state.
+- **`MarkdownFormatter`** — Helper for constructing Markdown documents.
+- **`ReadmeGenerator`** — Generate README.md from AnalysisResult.
+- **`CoverageGenerator`** — Generate docs/coverage.md — docstring coverage report.
+- **`DepGraphGenerator`** — Generate docs/dependency-graph.md with Mermaid diagrams.
+- **`GenerateContext`** — Shared context passed to all generators during a run.
+- **`BaseGenerator`** — Abstract base for all documentation generators.
+- **`ChangelogEntry`** — A single changelog entry.
+- **`ChangelogGenerator`** — Generate CHANGELOG.md from git log and analysis diff.
+- **`ApiReferenceGenerator`** — Generate docs/api/ — per-module API reference from signatures.
+- **`ModuleDocsGenerator`** — Generate docs/modules/ — detailed per-module documentation.
+- **`MkDocsGenerator`** — Generate mkdocs.yml from the docs/ directory structure.
+- **`ExamplesGenerator`** — Generate examples/ — usage examples from public API signatures.
+- **`ReadmeGeneratorAdapter`**
+- **`ApiReferenceAdapter`**
+- **`ModuleDocsAdapter`**
+- **`ArchitectureAdapter`**
+- **`DepGraphAdapter`**
+- **`CoverageAdapter`**
+- **`ApiChangelogAdapter`**
+- **`ExamplesAdapter`**
+- **`MkDocsAdapter`**
+- **`ArchitectureGenerator`** — Generate docs/architecture.md — architecture overview with diagrams.
+- **`ApiChange`** — A single API change between two analysis snapshots.
+- **`ApiChangelogGenerator`** — Generate API changelog by diffing current analysis with a saved snapshot.
+- **`DefaultGroup`** — Click Group that routes unknown subcommands to 'generate'.
+- **`ReadmeConfig`** — Configuration for README generation.
+- **`DocsConfig`** — Configuration for docs/ generation.
+- **`ExamplesConfig`** — Configuration for examples/ generation.
+- **`SyncConfig`** — Configuration for synchronization.
+- **`Code2DocsConfig`** — Main configuration for code2docs.
+- **`ProjectScanner`** — Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults.
+- **`DocstringInfo`** — Parsed docstring with sections.
+- **`DocstringExtractor`** — Extract and parse docstrings from AnalysisResult.
+- **`DependencyInfo`** — Information about a project dependency.
+- **`ProjectDependencies`** — All detected project dependencies.
+- **`DependencyScanner`** — Scan and parse project dependency files.
+- **`Endpoint`** — Represents a detected web endpoint.
+- **`EndpointDetector`** — Detects web endpoints from decorator patterns in source code.
+
+### Functions
+
+- `start_watcher(project_path, config)` — Start watching project for file changes and auto-resync docs.
+- `generate_badges(project_name, badge_types, stats, deps)` — Generate shields.io badge Markdown strings.
+- `generate_toc(markdown_content, max_depth)` — Generate a table of contents from Markdown headings.
+- `extract_headings(content, max_depth)` — Extract headings from Markdown content.
+- `generate_readme(project_path, output, sections, sync_markers, config)` — Convenience function to generate a README.
+- `generate_docs(project_path, config)` — High-level function to generate all documentation.
+- `main()` — code2docs — Auto-generate project documentation from source code.
+- `generate(project_path, config_path, readme_only, sections, output, verbose, dry_run)` — Generate documentation (default command).
+- `sync(project_path, config_path, verbose, dry_run)` — Synchronize documentation with source code changes.
+- `watch(project_path, config_path, verbose)` — Watch for file changes and auto-regenerate docs.
+- `init(project_path, output)` — Initialize code2docs.yaml configuration file.
+- `analyze_and_document(project_path, config)` — Convenience function: analyze a project in one call.
+
+## Project Structure
+
+📄 `__main__`
+📦 `analyzers`
+📄 `analyzers.dependency_scanner` (6 functions, 3 classes)
+📄 `analyzers.docstring_extractor` (10 functions, 2 classes)
+📄 `analyzers.endpoint_detector` (3 functions, 2 classes)
+📄 `analyzers.project_scanner` (4 functions, 1 classes)
+📄 `base` (3 functions, 2 classes)
+📄 `cli` (10 functions, 1 classes)
+📦 `code2docs` (1 functions)
+📄 `config` (2 functions, 5 classes)
+📦 `formatters`
+📄 `formatters.badges` (2 functions)
+📄 `formatters.markdown` (13 functions, 1 classes)
+📄 `formatters.toc` (3 functions)
+📦 `generators` (1 functions)
+📄 `generators._registry_adapters` (18 functions, 9 classes)
+📄 `generators.api_changelog_gen` (9 functions, 2 classes)
+📄 `generators.api_reference_gen` (11 functions, 1 classes)
+📄 `generators.architecture_gen` (6 functions, 1 classes)
+📄 `generators.changelog_gen` (6 functions, 2 classes)
+📄 `generators.coverage_gen` (7 functions, 1 classes)
+📄 `generators.depgraph_gen` (9 functions, 1 classes)
+📄 `generators.examples_gen` (12 functions, 1 classes)
+📄 `generators.mkdocs_gen` (4 functions, 1 classes)
+📄 `generators.module_docs_gen` (17 functions, 1 classes)
+📄 `generators.readme_gen` (14 functions, 1 classes)
+📄 `registry` (4 functions, 1 classes)
+📦 `sync`
+📄 `sync.differ` (7 functions, 2 classes)
+📄 `sync.updater` (2 functions, 1 classes)
+📄 `sync.watcher` (1 functions)
+
+
+<!-- code2docs:end -->

code2docs/__init__.py

@@ -5,7 +5,7 @@
 README.md, API references, module docs, examples, and architecture diagrams.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __author__ = "Tom Sapletta"
 
 from .config import Code2DocsConfig

code2docs/cli.py

@@ -88,6 +88,25 @@ def init(project_path, output):
     click.echo(f"Created {out_path}")
 
 
+@main.command()
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
+@click.option("--target", "-t", default=80, type=int, help="Docstring coverage target (%)")
+def check(project_path, config_path, target):
+    """Health check — verify documentation completeness."""
+    config = _load_config(project_path, config_path)
+    _run_check(project_path, config, target)
+
+
+@main.command()
+@click.argument("project_path", default=".", type=click.Path(exists=True))
+@click.option("--config", "-c", "config_path", default=None, help="Path to code2docs.yaml")
+def diff(project_path, config_path):
+    """Preview what would change without writing anything."""
+    config = _load_config(project_path, config_path)
+    _run_diff(project_path, config)
+
+
 def _load_config(project_path: str, config_path: Optional[str] = None) -> Code2DocsConfig:
     """Load configuration, auto-detecting code2docs.yaml if present."""
     project = Path(project_path).resolve()
@@ -184,3 +203,85 @@ def _run_watch(project_path: str, config: Code2DocsConfig):
     project = Path(project_path).resolve()
     click.echo(f"👁 Watching {project.name} for changes... (Ctrl+C to stop)")
     start_watcher(str(project), config)
+
+
+def _run_check(project_path: str, config: Code2DocsConfig, target: int = 80):
+    """Run documentation health check."""
+    from .analyzers.project_scanner import ProjectScanner
+    from .analyzers.docstring_extractor import DocstringExtractor
+
+    project = Path(project_path).resolve()
+    click.echo(f"🩺 code2docs check: {project.name}\n")
+
+    scanner = ProjectScanner(config)
+    result = scanner.analyze(str(project))
+
+    score = 0
+    total = 0
+
+    # Check README
+    total += 1
+    readme = project / config.readme_output
+    if readme.exists():
+        click.echo("  ✅ README.md exists")
+        score += 1
+    else:
+        click.echo("  ❌ README.md missing")
+
+    # Check docs/
+    docs_dir = project / config.output
+    for subdir, label in [("api", "API reference"), ("modules", "Module docs")]:
+        total += 1
+        d = docs_dir / subdir
+        if d.exists() and any(d.iterdir()):
+            count = sum(1 for f in d.glob("*.md"))
+            click.echo(f"  ✅ {label}: {count} files")
+            score += 1
+        else:
+            click.echo(f"  ❌ {label}: missing or empty")
+
+    # Check examples/
+    total += 1
+    ex_dir = project / "examples"
+    if ex_dir.exists() and any(ex_dir.iterdir()):
+        count = sum(1 for f in ex_dir.glob("*.py"))
+        click.echo(f"  ✅ examples/: {count} files")
+        score += 1
+    else:
+        click.echo(f"  ❌ examples/: missing or empty")
+
+    # Docstring coverage
+    total += 1
+    extractor = DocstringExtractor()
+    report = extractor.coverage_report(result)
+    coverage = report.get("overall_coverage", 0)
+    if coverage >= target:
+        click.echo(f"  ✅ Docstring coverage: {coverage:.0f}% (target: {target}%)")
+        score += 1
+    else:
+        click.echo(f"  ⚠️  Docstring coverage: {coverage:.0f}% (target: {target}%)")
+
+    click.echo(f"\n  Score: {score}/{total}")
+
+
+def _run_diff(project_path: str, config: Code2DocsConfig):
+    """Preview documentation changes without writing."""
+    from .analyzers.project_scanner import ProjectScanner
+    from .base import GenerateContext
+    from .registry import GeneratorRegistry
+    from .generators._registry_adapters import ALL_ADAPTERS
+
+    project = Path(project_path).resolve()
+    click.echo(f"🔍 code2docs diff: {project.name}\n")
+
+    scanner = ProjectScanner(config)
+    result = scanner.analyze(str(project))
+
+    docs_dir = project / config.output
+    ctx = GenerateContext(project=project, docs_dir=docs_dir, dry_run=True)
+
+    registry = GeneratorRegistry()
+    for adapter_cls in ALL_ADAPTERS:
+        registry.add(adapter_cls(config, result))
+
+    registry.run_all(ctx)

code2docs/docs/api-changelog.md

@@ -0,0 +1,4 @@
+# code2docs — API Changelog
+
+> No previous API snapshot found. Run `code2docs generate` to create a baseline.
+> Future runs will show changes here.

code2docs/docs/api/index.md

@@ -0,0 +1,37 @@
+# API Reference
+
+> Auto-generated from 31 modules | 185 functions | 42 classes
+
+## Modules
+
+- [`__main__`](module___main__.md) — 0 functions, 0 classes
+- [`analyzers`](module_analyzers.md) — 0 functions, 0 classes
+- [`analyzers.dependency_scanner`](module_analyzers_dependency_scanner.md) — 6 functions, 3 classes
+- [`analyzers.docstring_extractor`](module_analyzers_docstring_extractor.md) — 10 functions, 2 classes
+- [`analyzers.endpoint_detector`](module_analyzers_endpoint_detector.md) — 3 functions, 2 classes
+- [`analyzers.project_scanner`](module_analyzers_project_scanner.md) — 4 functions, 1 classes
+- [`base`](module_base.md) — 3 functions, 2 classes
+- [`cli`](module_cli.md) — 10 functions, 1 classes
+- [`code2docs`](module_code2docs.md) — 1 functions, 0 classes
+- [`config`](module_config.md) — 2 functions, 5 classes
+- [`formatters`](module_formatters.md) — 0 functions, 0 classes
+- [`formatters.badges`](module_formatters_badges.md) — 2 functions, 0 classes
+- [`formatters.markdown`](module_formatters_markdown.md) — 13 functions, 1 classes
+- [`formatters.toc`](module_formatters_toc.md) — 3 functions, 0 classes
+- [`generators`](module_generators.md) — 1 functions, 0 classes
+- [`generators._registry_adapters`](module_generators__registry_adapters.md) — 18 functions, 9 classes
+- [`generators.api_changelog_gen`](module_generators_api_changelog_gen.md) — 9 functions, 2 classes
+- [`generators.api_reference_gen`](module_generators_api_reference_gen.md) — 11 functions, 1 classes
+- [`generators.architecture_gen`](module_generators_architecture_gen.md) — 6 functions, 1 classes
+- [`generators.changelog_gen`](module_generators_changelog_gen.md) — 6 functions, 2 classes
+- [`generators.coverage_gen`](module_generators_coverage_gen.md) — 7 functions, 1 classes
+- [`generators.depgraph_gen`](module_generators_depgraph_gen.md) — 9 functions, 1 classes
+- [`generators.examples_gen`](module_generators_examples_gen.md) — 12 functions, 1 classes
+- [`generators.mkdocs_gen`](module_generators_mkdocs_gen.md) — 4 functions, 1 classes
+- [`generators.module_docs_gen`](module_generators_module_docs_gen.md) — 17 functions, 1 classes
+- [`generators.readme_gen`](module_generators_readme_gen.md) — 14 functions, 1 classes
+- [`registry`](module_registry.md) — 4 functions, 1 classes
+- [`sync`](module_sync.md) — 0 functions, 0 classes
+- [`sync.differ`](module_sync_differ.md) — 7 functions, 2 classes
+- [`sync.updater`](module_sync_updater.md) — 2 functions, 1 classes
+- [`sync.watcher`](module_sync_watcher.md) — 1 functions, 0 classes

code2docs/docs/api/module___main__.md

@@ -0,0 +1,3 @@
+# `__main__`
+
+> Source: `/home/tom/github/wronai/code2docs/code2docs/__main__.py`