From 8ba9d0aeb9581ce4619976e8cdbc99208f68a10f Mon Sep 17 00:00:00 2001
From: Keith Guerin <keithguerin@gmail.com>
Date: Tue, 31 Mar 2026 14:14:00 -0700
Subject: [PATCH] docs(ux): enforce procedures for autogenerated files and
 settings

---
 packages/extensions/gemini-cli-ux/GEMINI.md         | 11 +++++++++++
 .../gemini-cli-ux/skills/ux-writer/SKILL.md         | 13 +++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/packages/extensions/gemini-cli-ux/GEMINI.md b/packages/extensions/gemini-cli-ux/GEMINI.md
index cfccdd0112..e078c51e61 100644
--- a/packages/extensions/gemini-cli-ux/GEMINI.md
+++ b/packages/extensions/gemini-cli-ux/GEMINI.md
@@ -71,6 +71,17 @@ underlying "rigor."
     to ensure PRs remain tight and clean. Do not make sweeping, loosely tied
     changes or opportunistic refactors. If a scope change or expansion is
     recommended, you MUST ask the user for input and receive approval FIRST.
+11. **Autogenerated Files & Sources of Truth**: NEVER manually edit
+    autogenerated blocks (e.g., between `<!-- SETTINGS-AUTOGEN:START -->` and
+    `END` in `docs/cli/settings.md`). To prevent sweeping, unnecessary diffs and
+    CI failures:
+    - **Modify the Source of Truth**: Treat
+      `packages/cli/src/config/settingsSchema.ts` as the ONLY place to edit
+      settings.
+    - **Use the Automation**: Run `npm run docs:settings` after making schema
+      changes. A large diff due to Markdown table re-alignment is expected.
+    - **Pre-push Validation**: Always run `npm run lint` locally before pushing
+      to catch any formatting mismatches early.
 
 ## Mandatory Workflow Triggers
 
diff --git a/packages/extensions/gemini-cli-ux/skills/ux-writer/SKILL.md b/packages/extensions/gemini-cli-ux/skills/ux-writer/SKILL.md
index b1f13b6ee0..898465ea37 100644
--- a/packages/extensions/gemini-cli-ux/skills/ux-writer/SKILL.md
+++ b/packages/extensions/gemini-cli-ux/skills/ux-writer/SKILL.md
@@ -88,6 +88,19 @@ If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and
 descriptions specifically follow the unique [Settings
 guidelines](./references/settings.md).
 
+**CRITICAL: Autogenerated Files & Sources of Truth**
+NEVER manually edit or suggest direct edits to the autogenerated table in
+`docs/cli/settings.md` (between the `<!-- SETTINGS-AUTOGEN:START -->` and
+`END` markers).
+1. Treat `packages/cli/src/config/settingsSchema.ts` as the ONLY source of truth
+   for setting definitions, labels, and defaults.
+2. After modifying the schema, you MUST run the automation script:
+   `npm run docs:settings`.
+3. Do not attempt to "fix" or minimize the resulting diff in `docs/cli/settings.md`.
+   Because Markdown tables use fixed-width padding, changing the length of a
+   single value will cause the script to re-align the entire column. This large
+   formatting diff is expected and required by CI.
+
 ## Output format
 When suggesting changes, always present your review using the following list
 format. Do not provide suggestions outside of this list..