Docs: add Admin Describe UI and no-append usage

README.md

@@ -450,3 +450,60 @@ Troubleshooting:
 - If Gemini returns HTTP 429 RESOURCE_EXHAUSTED, ensure the API key is attached to a project with billing and the Generative Language API quota enabled.
 - If you see "Argument list too long" errors, ensure generate_data.sh is the deployed version that uses the Python builder (it avoids embedding large base64 arguments directly into jq/curl).
 - Run the script as www-data to avoid permission problems reading /etc/mvlog/gemini.env and to create files owned by the webserver.
+
+## Admin Describe UI & synchronous generator
+
+The admin interface includes a new "Describe" button on each input-dir row (Edit tab). Clicking it runs a server-side synchronous helper which invokes the Gemini-based generator in "no-append" mode and returns the generated description in a popup. From the popup you can choose "Use in form" to copy the description into the edit form's Description textarea. The description is written to disk only when you click "Save changes" in the edit form.
+
+Server-side helper:
+
+- lib/generate_data_sync.php — authenticated endpoint used by the admin UI. It runs bin/generate_data.sh with a trailing `no-append` argument so data.txt is not modified automatically and returns the generated JSON/description to the browser.
+
+Script usage (no-append, run as the web user):
+
+sudo -u www-data /var/www/html/mvlog/bin/generate_data.sh /var/www/html/mvlog/in-dir/20230630_napoli "Naples" "Naples, Italy" 16 no-append
+
+Notes:
+- The admin UI uses 16 sample frames by default when requesting a description.
+- The generator always writes the raw AI output to `<inputdir>/gemini_generated.json`. During debug runs the request/response may be saved as `debug_request.json`/`debug_response.json` inside the input dir for inspection.
+- If the Gemini API returns an error (HTTP 429 or 503) the response and details are written to the job log (`<inputdir>/generate_data.log`) and debug response file when available.
+
+If you prefer a background/async workflow instead of the synchronous popup, the endpoint and UI can be adjusted to start the job in the background and poll for results instead.
+
+## Admin Describe UI & synchronous generator
+
+The admin interface includes a new "Describe" button on each input-dir row (Edit tab). Clicking it runs a server-side synchronous helper which invokes the Gemini-based generator in "no-append" mode and returns the generated description in a popup. From the popup you can choose "Use in form" to copy the description into the edit form's Description textarea. The description is written to disk only when you click "Save changes" in the edit form.
+
+Server-side helper:
+
+- lib/generate_data_sync.php — authenticated endpoint used by the admin UI. It runs bin/generate_data.sh with a trailing `no-append` argument so data.txt is not modified automatically and returns the generated JSON/description to the browser.
+
+Script usage (no-append, run as the web user):
+
+sudo -u www-data /var/www/html/mvlog/bin/generate_data.sh /var/www/html/mvlog/in-dir/20230630_napoli "Naples" "Naples, Italy" 16 no-append
+
+Notes:
+- The admin UI uses 16 sample frames by default when requesting a description.
+- The generator always writes the raw AI output to `<inputdir>/gemini_generated.json`. During debug runs the request/response may be saved as `debug_request.json`/`debug_response.json` inside the input dir for inspection.
+- If the Gemini API returns an error (HTTP 429 or 503) the response and details are written to the job log (`<inputdir>/generate_data.log`) and debug response file when available.
+
+If you prefer a background/async workflow instead of the synchronous popup, the endpoint and UI can be adjusted to start the job in the background and poll for results instead.
+
+## Admin Describe UI & synchronous generator
+
+The admin interface includes a new "Describe" button on each input-dir row (Edit tab). Clicking it runs a server-side synchronous helper which invokes the Gemini-based generator in "no-append" mode and returns the generated description in a popup. From the popup you can choose "Use in form" to copy the description into the edit form's Description textarea. The description is written to disk only when you click "Save changes" in the edit form.
+
+Server-side helper:
+
+- lib/generate_data_sync.php — authenticated endpoint used by the admin UI. It runs bin/generate_data.sh with a trailing `no-append` argument so data.txt is not modified automatically and returns the generated JSON/description to the browser.
+
+Script usage (no-append, run as the web user):
+
+sudo -u www-data /var/www/html/mvlog/bin/generate_data.sh /var/www/html/mvlog/in-dir/20230630_napoli "Naples" "Naples, Italy" 16 no-append
+
+Notes:
+- The admin UI uses 16 sample frames by default when requesting a description.
+- The generator always writes the raw AI output to `<inputdir>/gemini_generated.json`. During debug runs the request/response may be saved as `debug_request.json`/`debug_response.json` inside the input dir for inspection.
+- If the Gemini API returns an error (HTTP 429 or 503) the response and details are written to the job log (`<inputdir>/generate_data.log`) and debug response file when available.
+
+If you prefer a background/async workflow instead of the synchronous popup, the endpoint and UI can be adjusted to start the job in the background and poll for results instead.