feat: use file-wins mkdocs configs with --refresh; wiki template in mongo-ops style

docs/wiki/05_development/05_mkdocs_configs.md

@@ -0,0 +1,48 @@
+# MkDocs Configuration Model
+
+Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A
+repo that documents kind `{kind}` carries a config at `docs/mkdocs.{kind}.yml`
+that sets `docs_dir` to the kind's source directory and `site_dir` to
+`../site/{kind}`.
+
+## File wins
+
+`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:
+
+- **Absent** — `doc-forge build --{kind}` materializes a copy from the
+  packaged templates (see below) and then builds `site/{kind}`.
+- **Present** — the build uses the file verbatim. Edits to the theme, palette,
+  plugins, markdown extensions, nav, or `site_dir` are respected as-is.
+- **`--refresh`** — force-regenerates the file from the templates,
+  replacing any local changes.
+
+Because a present file is never rewritten, rerunning a build is a no-op for
+versioned configs: the working tree stays clean.
+
+## Templates
+
+The built-in defaults live in `docforge/templates/`:
+
+| File                  | Role                                          |
+|-----------------------|-----------------------------------------------|
+| `mkdocs.common.yml`   | Shared theme + markdown extensions            |
+| `mkdocs.lib.yml`      | `mkdocstrings` handler for library reference  |
+| `mkdocs.api.yml`      | Swagger/OpenAPI plugins and API-side features |
+| `mkdocs.wiki.yml`     | Wiki look: horizontal `navigation.tabs` header, blue grey/teal palette, Roboto |
+
+A per-kind config is generated by deep-merging the common template with the
+kind fragment, then filling in generation-time values (`site_name`,
+`docs_dir`, `site_dir`, `nav`, API `site_description`/`site_author`, and the
+theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
+built-in templates entirely.
+
+## Supported layouts
+
+- **Per-kind config** — the standard layout; each kind builds to
+  `site/{kind}` and is served under `/<repo>/{kind}/`.
+- **Legacy root config** — a repo with a single kind may instead author root
+  `mkdocs.yml` (for example mongo-ops, whose wiki uses `docs_dir: docs/wiki`).
+  doc-forge never reads or writes root `mkdocs.yml`; the docs service maps the
+  kind to the root `site/` dir in this case.
+
+Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.