docs: smart init in commands, config, READMEs + test count 706

- Add --pyproject flag to commands.md (EN/IT)
- Add --pyproject to Getting Started in configuration/index.md (EN/IT)
- Add Project setup section with zenzic init to README.md and README.it.md
- Add smart init entry to CHANGELOG.md and RELEASE.md
- Update test counts 694 → 706 across CHANGELOG.md and RELEASE.md

Author: PythonWoods-Dev

CHANGELOG.md

@@ -77,6 +77,12 @@ Versions follow [Semantic Versioning](https://semver.org/).
   - `src/<module>/rules.py` module-level `BaseRule` template
   - minimal docs fixture and `zenzic.toml` so `zenzic check all` can run
 
+- **Smart Initialization — `zenzic init --pyproject`** — when `pyproject.toml`
+  exists, `zenzic init` interactively asks whether to embed configuration as a
+  `[tool.zenzic]` table instead of creating a standalone `zenzic.toml`.  Pass
+  `--pyproject` to skip the prompt.  `--force` overwrites an existing
+  `[tool.zenzic]` section.  Engine auto-detection works in both modes.
+
 - `examples/plugin-scaffold-demo/` — living scaffold output fixture for SDK
   integration checks and contributor onboarding.
 
@@ -254,7 +260,7 @@ Versions follow [Semantic Versioning](https://semver.org/).
   runner: `python3 -m pytest -x`, target: `src/zenzic/core/rules.py`.
 - **Performance baseline** relaxed from 150 ms → 200 ms for 5 000 in-memory
   resolutions to accommodate CI/nox environmental variance (resolver is O(1)).
-- **694 tests pass.** `just preflight` — all gates green:
+- **706 tests pass.** `just preflight` — all gates green:
   ruff ✓ · mypy ✓ · pytest 80%+ coverage ✓ · REUSE ✓ · zenzic self-audit ✓ · mkdocs build --strict ✓.
 
 ## [0.5.0a2] — 2026-04-03 — The Refined Sentinel: Lean Package & Unified Workflow

README.it.md

@@ -167,6 +167,16 @@ Zenzic esegue un'**analisi statica** dei tuoi file di configurazione (`mkdocs.ym
 
 Questo significa che **non è necessario installare** MkDocs, Material for MkDocs o altri plugin di build nel tuo ambiente di linting. Zenzic rimane leggero e privo di dipendenze, rendendolo ideale per pipeline CI/CD veloci e isolate.
 
+### Setup progetto
+
+```bash
+zenzic init             # crea zenzic.toml con engine rilevato automaticamente
+zenzic init --pyproject # incorpora [tool.zenzic] in pyproject.toml
+```
+
+Quando `pyproject.toml` esiste, `zenzic init` chiede interattivamente se incorporare
+la configurazione lì. Usa `--pyproject` per saltare il prompt.
+
 ---
 
 ## Utilizzo CLI

README.md

@@ -362,6 +362,16 @@ This means you **do not need to install** MkDocs, Material for MkDocs, or any ot
 > (PDFs, ZIPs), add their glob patterns to `excluded_build_artifacts` in `zenzic.toml`
 > rather than pre-generating them. See the [First-Class Integrations](#first-class-integrations) section above.
 
+### Project setup
+
+```bash
+zenzic init             # creates zenzic.toml with auto-detected engine
+zenzic init --pyproject # embeds [tool.zenzic] in pyproject.toml instead
+```
+
+When `pyproject.toml` exists, `zenzic init` asks interactively whether to embed
+configuration there. Pass `--pyproject` to skip the prompt.
+
 ---
 
 ## CLI usage

RELEASE.md

@@ -112,6 +112,24 @@ serving as both a DX reference and a quality-gate integration test.
 
 ---
 
+#### ⚡ Smart Initialization — `zenzic init --pyproject`
+
+`zenzic init` now detects `pyproject.toml` in the project root and interactively
+asks whether to embed configuration as a `[tool.zenzic]` table instead of creating
+a standalone `zenzic.toml`.
+
+```bash
+zenzic init             # interactive: asks if pyproject.toml exists
+zenzic init --pyproject # skip the prompt, write directly into pyproject.toml
+zenzic init --force     # overwrite existing config (both modes)
+```
+
+Engine auto-detection (`mkdocs.yml` → `engine = "mkdocs"`, `zensical.toml` →
+`engine = "zensical"`) works in both standalone and pyproject modes.  When no
+engine config file is found, vanilla defaults apply.
+
+---
+
 #### 🛡️ Z001 / Z002 Split — Errors vs Warnings for Link Issues (closes #6)
 
 `VSMBrokenLinkRule` now distinguishes:
@@ -165,7 +183,7 @@ repos:
 ### Quality Gates
 
 ```text
-pytest             694 passed, 0 failed
+pytest             706 passed, 0 failed
 coverage           80%+ branch (gate: ≥ 80%)
 mutation score     86.7% (242/279 killed on rules.py — target: 75%)
 ruff check src/    0 violations
@@ -243,7 +261,7 @@ installed for `zenzic check all` to pass.
 
 All validation logic in Zenzic lives in pure functions: no file I/O, no network access, no global
 state, no terminal output. I/O happens only at the edges — CLI wrappers that read files and print
-findings. Pure functions are trivially testable (694 passing tests, ≥ 80% branch-coverage gate), composable
+findings. Pure functions are trivially testable (706 passing tests, ≥ 80% branch-coverage gate), composable
 into higher-order pipelines, and deterministic across environments.
 
 The score you get on a developer laptop is the score CI gets. The score CI gets is the score you
@@ -569,7 +587,7 @@ and `diff` Python APIs has been renamed to `output_format` — update any progra
 
 ```text
 zenzic check all   # self-dogfood: 7/7 OK
-pytest             # 694 passed, 0 failed
+pytest             # 706 passed, 0 failed
 coverage           # ≥ 80% branch (hard gate)
 mutation score     # 86.7% (242/279 killed on rules.py)
 ruff check .       # 0 violations

docs/configuration/index.md

@@ -26,10 +26,14 @@ Use `zenzic init` to scaffold the file automatically. It detects the documentati
 project root (e.g. `mkdocs.yml`) and pre-sets `engine` in `[build_context]`:
 
 ```bash
-zenzic init          # creates zenzic.toml with detected engine
-zenzic init --force  # overwrite an existing file
+zenzic init             # creates zenzic.toml with detected engine
+zenzic init --pyproject # embeds [tool.zenzic] in pyproject.toml instead
+zenzic init --force     # overwrite an existing file
 ```
 
+When `pyproject.toml` exists, `zenzic init` asks whether to embed the configuration there
+as a `[tool.zenzic]` table.  Pass `--pyproject` to skip the interactive prompt.
+
 When you need to customise behaviour — for example, to raise the word-count threshold for concise
 technical reference pages, or to add team-specific placeholder patterns — create or edit
 `zenzic.toml` at the repository root:

docs/it/configuration/index.md

@@ -29,10 +29,14 @@ Usa `zenzic init` per scaffoldare il file automaticamente. Rileva il motore di d
 dalla root del progetto (es. `mkdocs.yml`) e preimposta `engine` in `[build_context]`:
 
 ```bash
-zenzic init          # crea zenzic.toml con engine rilevato
-zenzic init --force  # sovrascrive un file esistente
+zenzic init             # crea zenzic.toml con engine rilevato
+zenzic init --pyproject # incorpora [tool.zenzic] in pyproject.toml
+zenzic init --force     # sovrascrive un file esistente
 ```
 
+Quando `pyproject.toml` esiste, `zenzic init` chiede se incorporare la configurazione lì
+come tabella `[tool.zenzic]`.  Usa `--pyproject` per saltare il prompt interattivo.
+
 Crea o modifica `zenzic.toml` nella root del repository quando hai bisogno di personalizzare il
 comportamento:
 

docs/it/usage/commands.md

@@ -55,10 +55,21 @@ Puoi anche impostare `exit_zero = true` in `zenzic.toml` per renderlo il default
 
 ```bash
 zenzic init                               # Crea zenzic.toml nel progetto corrente
-zenzic init --force                       # Sovrascrive zenzic.toml esistente
+zenzic init --pyproject                   # Scrive la config in pyproject.toml [tool.zenzic]
+zenzic init --force                       # Sovrascrive la config esistente senza prompt
 zenzic init --plugin plugin-scaffold-demo # Crea un pacchetto SDK plugin
 ```
 
+**Rilevamento intelligente** — quando `pyproject.toml` esiste nella root del progetto,
+`zenzic init` chiede se incorporare la configurazione lì come tabella `[tool.zenzic]`
+invece di creare un file `zenzic.toml` separato.  Usa `--pyproject` per saltare il
+prompt e scrivere direttamente in `pyproject.toml`.
+
+Il rilevamento automatico dell'engine è incluso in entrambe le modalità: se `mkdocs.yml`
+o `zensical.toml` è presente, la configurazione generata preimposta il campo `engine`.
+Se non viene trovato alcun file di configurazione engine, si applicano i default
+vanilla (indipendenti dall'engine).
+
 `zenzic init --plugin <nome>` genera uno scheletro di pacchetto Python con
 entry-point `zenzic.rules` pronto all'uso e template `BaseRule`
 (`src/<modulo>/rules.py`). Include anche una fixture docs minima, cosi il

docs/usage/commands.md

@@ -54,10 +54,20 @@ You can also set `exit_zero = true` in `zenzic.toml` to make it the permanent de
 
 ```bash
 zenzic init                               # Scaffold zenzic.toml in the current project
-zenzic init --force                       # Overwrite existing zenzic.toml
+zenzic init --pyproject                   # Write config into pyproject.toml [tool.zenzic]
+zenzic init --force                       # Overwrite existing config without prompting
 zenzic init --plugin plugin-scaffold-demo # Scaffold a plugin SDK package
 ```
 
+**Smart detection** — when `pyproject.toml` exists in the project root, `zenzic init`
+asks whether to embed the configuration there as a `[tool.zenzic]` table instead of
+creating a separate `zenzic.toml`.  Pass `--pyproject` to skip the prompt and write
+directly into `pyproject.toml`.
+
+Engine auto-detection is included in both modes: if `mkdocs.yml` or `zensical.toml`
+is present, the generated configuration pre-sets the `engine` field accordingly.
+When no engine config file is found, vanilla (engine-agnostic) defaults apply.
+
 `zenzic init --plugin <name>` generates a Python package skeleton with a ready
 `zenzic.rules` entry-point and a `BaseRule` template (`src/<module>/rules.py`).
 It also includes a minimal docs fixture so the generated project can immediately