From 7278b522a78c8f22474ed7b992df898ac3f33d62 Mon Sep 17 00:00:00 2001
From: Forkless <devs@forkless.com>
Date: Mon, 11 May 2026 22:22:33 +0200
Subject: [PATCH] Document Makefile targets in README and developer docs

---
 README.md      | 17 +++++++++++++++++
 doc/index.html | 18 ++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/README.md b/README.md
index b04d293..42c46a6 100644
--- a/README.md
+++ b/README.md
@@ -211,6 +211,23 @@ includes/
 └── class-logger.php         # PSR-3 logger with dual-channel fallback
 ```
 
+### Build & Tooling
+
+The `Makefile` wraps the build and translation toolchain:
+
+```
+make build               → Create piperless-X.Y.Z.zip
+make translations        → Extract .pot → JSON, sync to all locales
+make json2po             → Convert JSON translations back to .po/.mo
+make check-translations  → Validate translation integrity
+make lock-translations   → Lock all locales for translation work
+make unlock-translations → Release all translation locks
+make translation-status  → Show lock/completion for each locale
+make clean               → Remove build artifacts
+```
+
+All tools run as standalone shell scripts in `tools/` — the Makefile is a convenience wrapper.
+
 See `doc/index.html` for full developer documentation with architecture diagram, method tables, and security model.
 
 
diff --git a/doc/index.html b/doc/index.html
index f171113..daef819 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -438,6 +438,24 @@ for deterministic attribution.
   <li>@ suppression on filesystem calls with error_clear_last() + log_last_error() for diagnostics</li>
 </ul>
 
+<h2 id="build">Build &amp; Tooling</h2>
+
+<p>The <code>Makefile</code> wraps the build and translation toolchain:</p>
+
+<table>
+<tr><th>Command</th><th>Action</th></tr>
+<tr><td><code>make build</code></td><td>Create piperless-X.Y.Z.zip</td></tr>
+<tr><td><code>make translations</code></td><td>Extract .pot → JSON, sync to all locales</td></tr>
+<tr><td><code>make json2po</code></td><td>Convert JSON translations back to .po/.mo</td></tr>
+<tr><td><code>make check-translations</code></td><td>Validate translation integrity</td></tr>
+<tr><td><code>make lock-translations</code></td><td>Lock all locales for translation work</td></tr>
+<tr><td><code>make unlock-translations</code></td><td>Release all translation locks</td></tr>
+<tr><td><code>make translation-status</code></td><td>Show lock/completion for each locale</td></tr>
+<tr><td><code>make clean</code></td><td>Remove build artifacts</td></tr>
+</table>
+
+<p>All tools run as standalone shell scripts in <code>tools/</code> — the Makefile is a convenience wrapper.</p>
+
 </main>
 </body>
 </html>