docs(wiki): added more rules and explanation on how to use the prompt in docforge wiki

README.md

@@ -547,6 +547,20 @@ Example:
 
 ---
 
+# Type parity (`.pyi` stubs and `py.typed`)
+
+Documented APIs ship matching type information:
+
+- Each `.py` module has a synchronized `.pyi` stub in the same package.
+- Packages expose a `py.typed` marker so type checkers (and consumers)
+  use the authored signatures instead of `Any`.
+- When signatures change, update the `.py` implementation and its `.pyi`
+  stub together.
+- Doc-forge documents the docstrings in `.py`; the `.pyi` stub is the
+  machine-consumable signature surface.
+
+---
+
 # Parsing guarantees
 
 GSDFC ensures doc-forge can deterministically extract:

docforge/__init__.py

@@ -546,6 +546,20 @@ Example:
 
 ---
 
+# Type parity (`.pyi` stubs and `py.typed`)
+
+Documented APIs ship matching type information:
+
+- Each `.py` module has a synchronized `.pyi` stub in the same package.
+- Packages expose a `py.typed` marker so type checkers (and consumers)
+  use the authored signatures instead of `Any`.
+- When signatures change, update the `.py` implementation and its `.pyi`
+  stub together.
+- Doc-forge documents the docstrings in `.py`; the `.pyi` stub is the
+  machine-consumable signature surface.
+
+---
+
 # Parsing guarantees
 
 GSDFC ensures doc-forge can deterministically extract:

docs/mcp/modules/docforge.cli.commands.json

@@ -557,21 +557,21 @@
         "name": "build",
         "kind": "function",
         "path": "docforge.cli.commands.build",
-        "signature": "<bound method Function.signature of Function('build', 40, 264)>",
+        "signature": "<bound method Function.signature of Function('build', 40, 284)>",
-        "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n    - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n      provided.\n    - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n      while `--mcp` emits a machine-readable bundle.\n\nArgs:\n    mcp (bool):\n        Enable MCP documentation generation.\n\n    mkdocs (bool):\n        Enable the lib MkDocs documentation generation.\n\n    api (bool):\n        Enable API documentation generation from an OpenAPI spec.\n\n    wiki (bool):\n        Build a hand-written wiki directory as its own MkDocs site.\n\n    module_is_source (bool):\n        Treat the specified module directory as the project root.\n\n    module (str | None):\n        Python module import path to document.\n\n    openapi_spec (Path | None):\n        Path to the OpenAPI JSON specification used for API docs.\n\n    project_name (str | None):\n        Optional override for the project name.\n\n    site_name (str | None):\n        Display name for the lib and wiki MkDocs sites.\n\n    docs_dir (Path):\n        Shared documentation root used for generated sources.\n    wiki_dir (Path):\n        Directory containing hand-written wiki markdown files.\n\n    nav_file (Path):\n        Path to the navigation specification file.\n\n    template (Path | None):\n        Optional custom MkDocs configuration template.\n\n    out_dir (Path):\n        Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError:\n        If required options are missing or conflicting."
+        "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n    - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n      provided.\n    - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n      while `--mcp` emits a machine-readable bundle.\n    - Configuration files are generated only when absent; an existing\n      `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n      rebaseline it from the templates.\n\nArgs:\n    mcp (bool):\n        Enable MCP documentation generation.\n\n    mkdocs (bool):\n        Enable the lib MkDocs documentation generation.\n\n    api (bool):\n        Enable API documentation generation from an OpenAPI spec.\n\n    wiki (bool):\n        Build a hand-written wiki directory as its own MkDocs site.\n\n    refresh (bool):\n        Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n        it already exists. By default, existing configs are used as-is.\n\n    module_is_source (bool):\n        Treat the specified module directory as the project root.\n\n    module (str | None):\n        Python module import path to document.\n\n    openapi_spec (Path | None):\n        Path to the OpenAPI JSON specification used for API docs.\n\n    project_name (str | None):\n        Optional override for the project name.\n\n    site_name (str | None):\n        Display name for the lib and wiki MkDocs sites.\n\n    docs_dir (Path):\n        Shared documentation root used for generated sources.\n    wiki_dir (Path):\n        Directory containing hand-written wiki markdown files.\n\n    nav_file (Path):\n        Path to the navigation specification file.\n\n    template (Path | None):\n        Optional custom MkDocs configuration template.\n\n    out_dir (Path):\n        Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError:\n        If required options are missing or conflicting."
       },
       "serve": {
         "name": "serve",
         "kind": "function",
         "path": "docforge.cli.commands.serve",
-        "signature": "<bound method Function.signature of Function('serve', 267, 367)>",
+        "signature": "<bound method Function.signature of Function('serve', 287, 387)>",
         "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n    mcp (bool):\n        Serve documentation using the MCP server.\n\n    mkdocs (bool):\n        Serve the MkDocs development site from ``--mkdocs-yml``.\n\n    lib (bool):\n        Serve the lib MkDocs site.\n\n    api (bool):\n        Serve the API MkDocs site.\n\n    wiki (bool):\n        Serve the wiki MkDocs site.\n\n    module (str | None):\n        Python module import path to serve via MCP.\n\n    mkdocs_yml (Path):\n        Path to the MkDocs configuration file.\n\n    out_dir (Path):\n        Root directory containing MCP documentation resources.\n\nRaises:\n    click.UsageError:\n        If invalid or conflicting options are provided."
       },
       "tree": {
         "name": "tree",
         "kind": "function",
         "path": "docforge.cli.commands.tree",
-        "signature": "<bound method Function.signature of Function('tree', 370, 406)>",
+        "signature": "<bound method Function.signature of Function('tree', 390, 426)>",
         "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n    module (str):\n        Python module import path to introspect.\n\n    project_name (str | None):\n        Optional name to display as the project root."
       },
       "Group": {

docs/mcp/modules/docforge.cli.json

@@ -689,21 +689,21 @@
             "name": "build",
             "kind": "function",
             "path": "docforge.cli.commands.build",
-            "signature": "<bound method Function.signature of Function('build', 40, 264)>",
+            "signature": "<bound method Function.signature of Function('build', 40, 284)>",
-            "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n    - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n      provided.\n    - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n      while `--mcp` emits a machine-readable bundle.\n\nArgs:\n    mcp (bool):\n        Enable MCP documentation generation.\n\n    mkdocs (bool):\n        Enable the lib MkDocs documentation generation.\n\n    api (bool):\n        Enable API documentation generation from an OpenAPI spec.\n\n    wiki (bool):\n        Build a hand-written wiki directory as its own MkDocs site.\n\n    module_is_source (bool):\n        Treat the specified module directory as the project root.\n\n    module (str | None):\n        Python module import path to document.\n\n    openapi_spec (Path | None):\n        Path to the OpenAPI JSON specification used for API docs.\n\n    project_name (str | None):\n        Optional override for the project name.\n\n    site_name (str | None):\n        Display name for the lib and wiki MkDocs sites.\n\n    docs_dir (Path):\n        Shared documentation root used for generated sources.\n    wiki_dir (Path):\n        Directory containing hand-written wiki markdown files.\n\n    nav_file (Path):\n        Path to the navigation specification file.\n\n    template (Path | None):\n        Optional custom MkDocs configuration template.\n\n    out_dir (Path):\n        Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError:\n        If required options are missing or conflicting."
+            "docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n    - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n      provided.\n    - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n      while `--mcp` emits a machine-readable bundle.\n    - Configuration files are generated only when absent; an existing\n      `docs/mkdocs.{kind}.yml` is used as-is. Pass `--refresh` to\n      rebaseline it from the templates.\n\nArgs:\n    mcp (bool):\n        Enable MCP documentation generation.\n\n    mkdocs (bool):\n        Enable the lib MkDocs documentation generation.\n\n    api (bool):\n        Enable API documentation generation from an OpenAPI spec.\n\n    wiki (bool):\n        Build a hand-written wiki directory as its own MkDocs site.\n\n    refresh (bool):\n        Regenerate ``docs/mkdocs.{kind}.yml`` from templates even when\n        it already exists. By default, existing configs are used as-is.\n\n    module_is_source (bool):\n        Treat the specified module directory as the project root.\n\n    module (str | None):\n        Python module import path to document.\n\n    openapi_spec (Path | None):\n        Path to the OpenAPI JSON specification used for API docs.\n\n    project_name (str | None):\n        Optional override for the project name.\n\n    site_name (str | None):\n        Display name for the lib and wiki MkDocs sites.\n\n    docs_dir (Path):\n        Shared documentation root used for generated sources.\n    wiki_dir (Path):\n        Directory containing hand-written wiki markdown files.\n\n    nav_file (Path):\n        Path to the navigation specification file.\n\n    template (Path | None):\n        Optional custom MkDocs configuration template.\n\n    out_dir (Path):\n        Output directory for generated MCP resources.\n\nRaises:\n    click.UsageError:\n        If required options are missing or conflicting."
           },
           "serve": {
             "name": "serve",
             "kind": "function",
             "path": "docforge.cli.commands.serve",
-            "signature": "<bound method Function.signature of Function('serve', 267, 367)>",
+            "signature": "<bound method Function.signature of Function('serve', 287, 387)>",
             "docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n    mcp (bool):\n        Serve documentation using the MCP server.\n\n    mkdocs (bool):\n        Serve the MkDocs development site from ``--mkdocs-yml``.\n\n    lib (bool):\n        Serve the lib MkDocs site.\n\n    api (bool):\n        Serve the API MkDocs site.\n\n    wiki (bool):\n        Serve the wiki MkDocs site.\n\n    module (str | None):\n        Python module import path to serve via MCP.\n\n    mkdocs_yml (Path):\n        Path to the MkDocs configuration file.\n\n    out_dir (Path):\n        Root directory containing MCP documentation resources.\n\nRaises:\n    click.UsageError:\n        If invalid or conflicting options are provided."
           },
           "tree": {
             "name": "tree",
             "kind": "function",
             "path": "docforge.cli.commands.tree",
-            "signature": "<bound method Function.signature of Function('tree', 370, 406)>",
+            "signature": "<bound method Function.signature of Function('tree', 390, 426)>",
             "docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n    module (str):\n        Python module import path to introspect.\n\n    project_name (str | None):\n        Optional name to display as the project root."
           },
           "Group": {

docs/wiki/03_conventions.md

@@ -20,13 +20,16 @@ Key rules:
 3. Use `Args:`, `Returns:`, `Raises:`, `Yields:`, `Notes:`, and `Example:`
    sections at function and method level.
 4. Always update the matching `.pyi` stub alongside the `.py` implementation.
+5. Every distributable package ships a `py.typed` marker so type checkers
+   consume the authored signatures instead of `Any`.
 
 ---
 
-## `.pyi` stubs
+## `.pyi` stubs and `py.typed`
 
 Every module ships a matching `.pyi` stub kept in sync with the `.py`
-implementation. When signatures change, update both files.
+implementation. When signatures change, update both files. Packages expose a
+`py.typed` marker so consumers and type checkers use the authored signatures.
 
 ---
 

docs/wiki/index.md

@@ -47,14 +47,19 @@ pip install docforge
 
 - **Source Code:** the `doc-forge` repository
 - **MCP Bundle:** generated by `doc-forge build --mcp --module docforge` into `docs/mcp/`
-- **Wiki Kind:** hand-written content lives in `docs/wiki/` or use the prompt mentioned below
+- **Wiki Kind:** hand-written content lives in `docs/wiki/`; use the prompt in the
+  wiki-related resource below
 ````markdown
 # AGENTS.md — Wiki Authoring Guide (Aetoskia)
 
 This file instructs AI agents how to create, extend, and maintain the wiki
-(`docs/wiki/**`) for any Aetoskia repository. The reference implementation is
+(`docs/wiki/**`) for any Aetoskia repository.
-`mongo-ops` — its wiki went through several revisions to reach the structure
+
-below and should be treated as the canonical example.
+> **Workflow:** this prompt covers **phase 2 only**. Phase 1 — writing GSDFC docstrings
+> (plus `.pyi` stubs and `py.typed`) — is done by the agent using the doc-forge MCP
+> bundle: `doc://modules/docforge` carries the full GSDFC spec. Write the wiki only
+> after docstrings exist and `doc-forge build --mcp --module <pkg>` produced the
+> repo's own bundle.
 
 ---
 
@@ -261,6 +266,10 @@ Variants:
 - Keep pages focused: one recipe/purpose per page. If a page balloons past
   ~10 KB, split it (add a numbered deep-dive page instead).
 - Match tone of existing pages in the repo before writing new ones.
+- Ground every `## 🚀 Example`, `💡 Tips`, and `📦 What's New?` row in the
+  library's actual source, tests, and its `docs/mcp` bundle — never invent
+  APIs or behavior. Signatures and exceptions come from the code; gotchas
+  come from the tests.
 
 ---