These are not theoretical rules. They came from things that actually broke.
AutoAI started as “an AI application.” Wire up a model, generate some articles, add a chatbot. How hard could it be?
Then the seemingly simple features started opening trapdoors.
What follows is the compressed version: twelve principles, each earned through a real failure. If one of them makes you think “wait — does MY system do that?”, follow its link into the deep dive.
Twelve principles. Each one is short on purpose — each links to the full investigation.
An LLM can return perfectly valid JSON that is completely wrong for your application.
AutoAI’s model kept returning an object where the contract demanded a string inside
outline[] — three retries, same wrong shape, because the nested schema never reached the model.
“If my model returns valid JSON, what exactly have I proved?”
Read the full case study →Having vectors in PostgreSQL proves vectors exist. It does not prove retrieval works.
The production database had real 2048-d embeddings while the chatbot answered “No relevant knowledge found” to everything.
“Can I prove every stage between the user’s question and the retrieved chunk?”
Explore the RAG chapter →A post can have an ID and no usable content. A run can exist and be stale. A document can exist and be invisible.
“View Article” appeared during generation because a placeholder post was reserved up-front — with empty content.
“Which of my UI actions are gated by IDs instead of business state?”
Read more →Correct code can still behave incorrectly because configuration resolution is wrong.
All nine AI roles pointed at a demo mock in production because env fallbacks fired where variables were missing — while the real key sat unconnected in another settings surface.
“For every external dependency: what is my source → precedence → validation → fallback?”
Read more →Never assume a model supports a feature — structured outputs, context length, pricing — verify against its live catalog.
Request tiers (json_schema → json_object → none) exist because capability flags
differ per model and drift over time.
“If my provider changes this model tomorrow, what breaks silently?”
Read more →An agent workflow is a persisted state machine with human gates — not a sequence of AI calls.
Published articles kept a run stuck in waiting_for_human: finalization updated one
pointer while regeneration had created multiple runs per post.
“When this workflow terminates, which related executions must sweep to terminal state?”
Read more →A knowledge-grounded assistant answers ONLY when retrieval proves relevance — otherwise it refuses without calling the model at all.
Asked about a president, AutoAI once answered from world knowledge next to a “no relevant knowledge found” banner. Both statements were true; zero grounding present.
“What stops my chatbot from being helpful outside its knowledge base?”
Read more →When output is wrong, decompose the path into measurable stages and find the earliest point where reality differs from expectation.
One diagnostic funnel turned three separate “RAG is broken” incidents into three precise root causes.
“Am I fixing the stage that lied — or the stage that looks suspicious?”
Read more →Local ≠ Vercel ≠ Neon ≠ OpenRouter. Each boundary adds failure modes your laptop never exercised.
Env-default fallbacks fire only where variables are missing — which happens first in production. File-based local databases are single-writer; smoke scripts see a different world than the app.
“Which of my assumptions survive the deploy boundary?”
Read more →A feature is finished when the actual deployed path passes — observed, not assumed.
Health endpoints, authenticated diagnostics, and network-level evidence turned “should work” into measured facts (12/12 calls to the right provider, exact similarities, zero non-200s).
“What would I need to SHOW someone that this works in production right now?”
Read more →Every control must derive from meaningful backend state, never from identifier existence or timers.
A voice-settings panel offered provider/model fields the reply pipeline never read, while omitting what it did consume. Settings UIs must expose the intersection of changeable and consumed.
“Does every option in my UI actually do something?”
Read the case study →Done = acceptance criteria passing in production. Not out-of-ideas. Not tired.
AutoAI’s freeze memo listed forbidden files by name while the last two fixes shipped — that memo is why the release happened.
“Is this defect blocking the core workflow — or just bothering me?”
Read more →This is the debugging method behind almost every fix in this guide — drawn here as the path every request takes through a RAG system:
The same method found the login bug (auth ✓ → cookie ✓ → navigation ✗) and the stuck agent runs (publish ✓ → finalize ✗). It works because it converts “something is broken” into “this stage returns something different from that expectation.”
The practical path — seven chapters, roughly four minutes each, in the order that builds the mental model fastest.
Sources of truth, failure boundaries, and why “where does truth live” decides everything downstream.
Architecture Before Implementation →Model capabilities, structured outputs, validation layers and fallback tiers.
AI Providers & Model Abstraction →The eleven-stage funnel, seven real ways it broke, and the checklist that finds the lying stage.
RAG: Never Trust the Surface →Persisted state machines, human gates, multi-execution entities and terminal sweeps.
Agent Pipelines Are State Machines →Every boundary between local and live — and the proof standard that closes them.
Local ≠ Production →Expected vs observed, stage decomposition, first divergence, regression lock.
First-Divergence Debugging →Seven production incidents with symptom, wrong assumption, root cause and transferable lesson.
Case Studies →Answer these twelve questions BEFORE writing code. Your future self debugs faster when these have answers. Click items as you settle them — progress is saved in this browser.
None of the principles above were invented beforehand. They were extracted — sometimes painfully — from real failures, debugging sessions and production verification runs. Below sits the complete library: twenty chapters, the full checklist, and seven case studies with the actual investigations.
Three retries, same wrong shape: an object where a string belonged, inside a perfectly parseable response.
Read the investigation →Published docs, real 2048-d embeddings, and “no relevant knowledge found” for every question.
Read the investigation →Regeneration creates multiple runs per post; finalization updated only one cached pointer.
Read the investigation →Auth returned 200 with a fresh cookie; the client router just refused to believe it.
Read the investigation →Direction flipped instantly; server-rendered strings waited for a full request nobody made.
Read the investigation →A reserved placeholder post made “View Article” true from millisecond one of generation.
Read the investigation →A full panel of provider/model fields the reply pipeline never read — while the real controls hid in plain sight.
Read the investigation →Lessons from building, debugging and shipping AutoAI for Nature — an AI-native content platform with a nine-agent editorial pipeline, grounded RAG chatbot and voice assistant — from first commit to a frozen V1 in production.
Most failed AI projects are not killed by models. They are killed by undefined scope, undefined "done", and endless polishing that replaces shipping.
AutoAI began with questions, not code: what happens when the pipeline finishes? Who decides an article is publishable? What if the model returns garbage? Answering those produced the review gate (waiting_for_human) and the mock-provider veto long before they were needed — which is why they held up under pressure.
"Done" must be observable behavior. For AutoAI V1 it was written down explicitly:
waiting_for_human.Every later "is this in scope?" argument was settled against those three lines.
Near release we froze explicitly: no dashboard redesign, no pipeline animation work, no new voice providers, no RAG edge calibration. Not because those don't matter — each one reopens verified surface area. The last commit is literally titled fix: finalize V1 article and voice UX. Finishing is a feature.
The most repeated mistake of the project: treating existence as readiness. A post row existed during generation → the UI showed "View Article". A knowledge document existed → everyone assumed retrieval worked. The cure was always the same: derive behavior from meaningful persisted state.
"The code works" ≠ "the product works." AutoAI passed hundreds of unit tests while production login hung on first click and RAG refused every question. Code correctness is one layer; product correctness is the whole path — browser → API → cookie → middleware → database → third-party API → back.
Architecture is deciding in advance where truth lives — so when reality disagrees with you, you know exactly which layer lied.
| Question | Single source of truth | What we stopped doing |
|---|---|---|
| Which model handles the strategist? | Purpose config chain: override row → connection default → bootstrap → fallback | Scattered DEFAULT_AI_* env reads per module |
| Is this document searchable? | status='active' + allowed source_type + matching embedding identity | Assuming "row exists" |
| Is the article viewable? | postStatus + postHasContent read live from DB | run.postId ? show : hide |
| User language? | autoai_locale cookie → messages + direction | Treating RTL direction as the language state |
An unanswered item here becomes a production incident later.
Draw them explicitly. AutoAI: provider failure ⇒ router tries primary, then fallback, then fails loudly (never silently degrades to mock). Publish-time indexing failure ⇒ surfaced in the API response and audit log. Grounding miss ⇒ deterministic refusal without calling the LLM at all. Every boundary drawn early became a place where failures were contained instead of spread.
AutoAI once shipped correct code that pointed all nine AI roles at a demo mock — because configuration resolution, not code, decided what ran.
Production threw, for every purpose:
AI is not configured for real generation:
idea: still points at the mock provider; strategist: still points at the mock provider; …Cause: the purpose resolver fell back to process.env.DEFAULT_AI_PROVIDER || "mock", those variables didn't exist on Vercel, and the admin's real OpenRouter key lived in an entirely separate settings surface. Two configuration layers, zero precedence between them.
effective = 1. explicit per-purpose override (Models page save)
2. connection default (Admin → AI Connections)
3. documented bootstrap (real credential + nothing configured)
4. demo / mock (dev & tests only)After this change, stale values could not defeat fresh ones, and a deployment holding only an environment key worked end-to-end without anyone re-typing secrets.
| Question | AutoAI example |
|---|---|
| Source | DB row / env var / admin UI |
| Precedence | override > default > bootstrap > fallback |
| Validation | pre-flight guard fails fast, naming every broken purpose |
| Fallback | documented and safe — never silent-mock in prod |
| Failure behavior | clear error listing exactly what misresolved |
The demo provider hard-fails outside automated tests via a guard only the test runner sets. That converted "accidentally shipped fake answers" from a maybe into an impossibility — while keeping mocks fully usable in unit tests.
Providers are swappable infrastructure with per-model capabilities — and every model response is untrusted input until validated.
Every stored embedding carries {provider, model, dimensions}, and queries refuse to compare vectors unless the identity matches exactly. That one rule prevents silent corruption whenever models change: vectors from different models must never coexist or mix.
The live provider catalog exposes context length, pricing, supported parameters and structured-output support per model. The Models UI renders it; the request layer consults it. Never assume a model supports JSON-schema mode — ask, and degrade deliberately when it doesn't.
Schema validation failed at "outline.0": Expected string, received object
— after 3 attempts on openrouter/openai/gpt-4o-miniThe model kept answering {"outline":[{"angle":"…","audience":"…"}]} where the contract demanded outline: string[]. The prompt embedded only top-level keys as null hints and the request used bare json_object mode — nested shape was pure guesswork, and retries replayed the same guesswork.
response_format: json_schema, strict when safe, with tiered downgrade json_schema → json_object → none.outline.0) into repair requests.items.type === "string".The router records every attempt (provider/model/latency/ok) and reports fallbackUsed. Fallback exists to survive outages — not to quietly swap a different, cheaper model whose outputs drift from everything you validated.
The most important section. In AutoAI, retrieval failed in production while the database contained exactly what everyone assumed it needed: published documents and real 2048-dimensional Nemotron vectors.
RAG is not one operation — it is a chain of filters, and any stage can silently reduce the result set to zero:
| Stage | Real failure | How we saw it |
|---|---|---|
| Status filter | Docs created as drafts stayed inactive forever — even after their post was approved and published, because the update helper ignored status/sourceType fields | Documents visible in admin UI, absent from every search |
| Source type | Same docs stuck as draft_article; retrieval whitelisted only article | Direct column inspection |
| Embedding identity | A whole identity group with (null, null, null) — created but never successfully indexed; plus any doc whose stored model string diverged from current config | GROUP BY provider,model,dims over the corpus showed an unreachable bucket |
| Language filter | UI locale restricted the corpus: English question + Persian-only corpus = zero candidates by construction | Funnel counts collapsed exactly at that stage; removed so the multilingual corpus is always searched and the answer language is handled separately |
| Threshold | Cross-language similarity varies wildly per pair: measured 0.224–0.511 for genuinely related fa↔en content against a fixed 0.4 cutoff | Live probes embedding real questions through the production model |
| Ingestion errors | Publish-time indexing failures swallowed by .catch(() => {}) — publish reported success while vectors never landed | Confident metadata next to empty vector tables |
| Lying metadata | chunk_count = 5 while zero rows existed in the chunks table (wiped by a failed full re-index) | Join count between documents and chunks |
The cure was instrumentation, not retrying. A diagnostic endpoint runs ONE real query and prints every stage:
{
"stages": { "totalVectorsInKb": 9, "vectorsInActiveDocs": 9,
"vectorsAfterSourceTypeFilter": 9,
"vectorsMatchingQueryIdentity": 9 },
"storedIdentities": [
{"provider":"openrouter","model":"nvidia/nemotron…","dimensions":2048,"documents":2,"vectors":9},
{"provider":"(null)","model":"(null)","dimensions":null,"documents":3,"vectors":0}
],
"topSimilarities":[0.7344, 0.7048, 0.6962],
"threshold": 0.4,
"hasRelevant": true
}The stage where a number collapses names the bug. That null-identity group is a smoking gun: three documents nobody could ever retrieve.
A RAG chatbot becomes a generic chatbot by accident — one helpful completion at a time.
User asked: "Who is the current president of the United States?" The product claimed to be knowledge-grounded; the assistant answered from world knowledge anyway, appended "No relevant knowledge found", and both statements were true. It was not grounded — it merely suggested sources when retrieval happened to work.
retrieval → does relevant knowledge exist? (measured)
policy → is answering allowed? (grounding guard)
generation → LLM sees ONLY permitted context (strict system rules)An agent pipeline is not "call AI several times". It is a stateful workflow with human gates, partial failures and multiple executions per entity.
AutoAI editorial flow: idea → strategist → researcher → writer → critic (+revision) → seo → publisher → final_critic → lessons, wrapped in run states queued → running → waiting_for_human → completed | failed | cancelled. Every step persists status, provider/model, latency, score, retries and error — the timeline is reconstructable from the database alone.
Production: articles visibly published, yet Admin → Agent Runs listed their runs as waiting_for_human. First hypotheses were wrong (frontend cache? wrong run updated?). The truth:
approveArticle() finalized ONLY posts.agent_run_id.
But regeneration creates a NEW run for the SAME post
and re-points posts.agent_run_id to it.
⇒ older linked runs stayed waiting_for_human forever.running rows from crashed workers need grace-period reclaim so everything terminates."The row exists" and "the entity is valid" are different claims. Confusing them is how products lie.
| Exists… | …but logically |
|---|---|
| post row during generation | content empty — nothing viewable |
| knowledge document row | inactive → invisible to retrieval |
| document chunk_count = 5 | zero rows in chunks table — lying metadata |
| vectors present | identity mismatched → unreachable by any query |
| agent run waiting_for_human | article already published — stale execution |
| voice settings panel rendered | fields the backend never consumed |
draft_article → article happens at publish), implemented in the data layer — not string cosmetics in the UI.postStatus, postHasContent) so clients cannot invent state.Content lives: create → draft → review → publish → index → update → re-index → delete. Related entities must move together through every transition.
Post ──▶ Agent Runs ──▶ Agent Steps
└────▶ Knowledge Document ──▶ Chunks ──▶ VectorsPublishing promotes the knowledge document (draft_article/inactive → article/active) and re-indexes it under the current embedding identity. Editing a published post re-syncs it. Deleting anything leaves zero orphans in both directions.
The production demo-data purge ran as a reviewed operation:
Some columns are load-bearing in ways normal types are not. Vector dimensions are the canonical case.
Moving embeddings from 1536 to 2048 dimensions is not an ALTER COLUMN. Old vectors are permanently incompatible with new queries — mixing them corrupts every similarity search. The order is fixed:
accept old vectors are dead
→ wipe/rebuild dependent vector data
→ migrate schema vector(1536) → vector(2048)
→ re-index EVERYTHING under the new model
→ verify identity metadata on every documentAutoAI ties the dimension to one constant used by both the column type and the runtime validator, with an explicit rule: vectors are never truncated or padded — mismatch fails loudly and demands full re-index.
local ≠ Vercel ≠ Neon ≠ OpenRouter. Every boundary adds failure modes your laptop never exercised.
|| "mock" became nine broken purposes).The discipline that ended AutoAI's longest debug loops — including two separate "impossible" production bugs.
Expected behavior → write it down first
Observed behavior → capture real evidence
Stages → decompose the path into measurable steps
Measure each stage → counters, values, statuses
FIRST divergence → earliest stage where expected ≠ observed
Fix root cause → that stage only
Regression test → lock the exact case
Production verify → prove it on the real path"Chat returns no knowledge for everything" decomposed into the §05 funnel. Per-stage counters immediately separated three distinct incidents: identity mismatch (null buckets), status/source-type staleness, and language-coupled corpora. Three root causes, one diagnostic endpoint, zero random code changes.
form → POST /api/auth/login → 200 + Set-Cookie ✓
→ router.push("/admin") ✗ client cache held the UNAUTHENTICATED payload
→ router.refresh() raced/cancelled the push
→ spinner never resolves
manual refresh → cache warm with fresh cookie → next click succeedsThe network tab proved authentication succeeded; measurement localized the divergence to the navigation stage. The fix (full-document navigation so middleware always sees the fresh cookie) was three lines. Guessing "session bug" would have rewritten working auth.
AutoAI grew from 49 to 83 tests across these fixes. But counts are trivia; layers are the point.
| Layer | Proves | AutoAI example |
|---|---|---|
| Unit | Pure decision logic | config-precedence matrix · view-article gate · refusal thresholds |
| Contract | Public shapes stay honest | voice settings expose exactly 3 real fields |
| Regression | The historical bug never returns | outline[0] object rejection · i18n key parity |
| Wire-level | Actual HTTP contracts | stubbed fetch asserting response_format.json_schema.strict + item types |
| Real provider | The model behaves | Persian/English structured outputs vs live gpt-4o-mini |
| Real database | Storage behaves | pgvector dims, orphan sweeps, funnel counters on Neon |
| Production smoke | Deployed path works | health + authenticated diagnostics on the live URL |
Also true in reverse: a wire-level test asserting request shape would have caught the bug before any deployment, without spending a single token. Layered tests exist so each layer catches what the previous one structurally cannot.
hasKey: true). Verified by scanning every admin response body for key fragments.Production report: switching to Persian left English strings everywhere; switching back flipped only direction while text stayed Persian.
locale ("fa" | "en")
├─▶ messages[locale]
└─▶ dir = rtl | ltr (derived — NEVER the language state)The switcher wrote the cookie and updated client dictionaries — but server-rendered components had already been generated under the old cookie. Direction flipped instantly (client effect); strings lagged until some later full request. Half-translated pages that looked like a rendering bug were a refresh-boundary bug.
router.refresh() so ALL server components re-render under the new cookie.isRTL(locale)) on both server render and client effect.dir — or setting
dir as if choosing a language — couples two systems that must evolve independently.During generation, users clicked "View Article" into an empty shell. The guard was run.postId != null — true from the moment the pipeline reserved a placeholder post.
| ID exists… | …≠ meaningful state |
|---|---|
| post.id | post has viewable content |
| knowledge_document.id | document searchable |
| agent_run.id | run currently executing |
| voice panel rendered | settings actually consumed by backend |
Fix pattern: expose REAL state through the API (postStatus, postHasContent read live from DB), gate through a pure function, cover with a matrix test (7 cases: empty draft hidden during queued/running/failed; published/needs_review/saved-draft visible).
The same principle caught the voice settings panel: it rendered inputs for fields the implementation never read (STT/TTS providers, LLM model pickers) while omitting what it DID consume. The rewrite exposed a live capability status (browser Web Speech API, supported languages, resolved engine) plus only the three genuinely configurable fields — verified by a contract test asserting the exact exposed key set.
Not every discovered defect belongs to the current release. AutoAI's final phase survived because scope was locked in writing — forbidden files listed by name.
| Class | Definition | Real example |
|---|---|---|
| P0 | Blocks core workflow / correctness / security | purposes→mock; RAG returning nothing; first-login hang |
| P1 | Important, contained fix | language-filtered retrieval; honest voice panel |
| P2 | Polish | pipeline animation, dashboard layout, loading micro-states |
| V2 | Future capability | new voice providers, image system, threshold calibration research |
Any YES → now. All NO → V2 backlog, written down, closed with a straight face.
Walk this before writing code — and again before shipping. Click items as you complete them.
Seven production incidents, compressed. Expand for symptom → wrong assumption → investigation → root cause → fix → transferable lesson.
Schema validation failed at "outline.0": Expected string, received object after 3 attempts on gpt-4o-mini — intermittent, real traffic only.
"We send the schema, so the model follows it." The 'schema' was top-level keys mapped to null; nested shapes were never communicated, and retries replayed identical ambiguity.
Reproduced live; captured actual request bodies; found bare json_object mode and null-hint prompts; confirmed the repair loop restated the same ambiguous hint.
Provider contract ≠ application contract. No native structured output; nested types existed nowhere outside Zod.
One Zod→JSON-Schema compiler feeding native json_schema mode (strict when safe) AND the prompt; tiered downgrade json_schema→json_object→none; strict local validation quoting paths into bounded repairs; wire-level regression tests asserting items.type=="string".
JSON is not validation. One canonical schema must feed provider, prompt, parser and validator — anything less invites drift between what you expect and what you asked for.
"No relevant knowledge" for every question while Neon held published documents and real 2048-d Nemotron vectors.
"Vectors exist ⇒ retrieval works."
Stage-by-stage funnel diagnosis: total vectors → active-docs → source-type → identity-match → similarities → threshold. Also direct probes embedding real questions through the production model.
Multiple stacked causes across incidents: documents stuck draft_article/inactive; a publish-time update helper silently ignoring those columns; null embedding-identity rows unreachable by any query; swallowed indexing errors faking success; a UI-language filter zeroing cross-language corpora.
Canonical promotion at publish; single authoritative indexer with loud failures; per-stage diagnostics endpoint; removal of locale-coupled corpus filtering; integrity checks (orphans, identity groups).
Never debug RAG as a unit. Instrument the funnel; the collapsing stage names the bug — and "vectors exist" is never evidence.
Admin → Agent Runs showed runs awaiting approval for articles that were already publicly published.
"Frontend shows stale data" / "the wrong run got updated." Both false.
Traced approval flow: finalize logic updated only posts.agent_run_id. But regeneration inserts a NEW run per post and re-points that column — older linked runs were orphaned in waiting state forever.
One-entity-one-execution assumption inside a multi-execution workflow; plus publish paths outside the review API never finalized anything.
finalizeWaitingRunsForPost(postId) sweeping every waiting_for_human run by foreign key; wired into approve, reject AND the shared status-transition service; idempotent; covered by matrix regression tests.
Workflows terminate by relationship sweeps, not pointer updates — and every path that changes business state must trigger the same terminal transitions.
Valid credentials + click → infinite spinner. Refresh → click again → success.
"Session bug" / "middleware rejects first cookie." Network tab disproved both: the login POST returned 200 with Set-Cookie on the FIRST attempt.
Stage-by-stage: auth ✓, cookie ✓, navigation ✗ — client router cache still held the unauthenticated /admin payload, and router.refresh() raced router.push(), leaving the spinner mounted.
Client-side navigation racing its own cache after an auth-state change that only the server had seen.
Full-document navigation post-login (window.location.assign to a sanitized internal target) so middleware always evaluates the fresh cookie; spinner resolves by page transition; open-redirect guard added.
Auth-state changes demand full navigations or explicit cache invalidation. Client caches do not know your cookie changed.
FA↔EN toggle flipped RTL/LTR instantly while most text remained in the previous language; other pages mixed languages entirely.
"Translation files are missing keys." Parity check showed 628=628 keys, zero gaps.
Compared client-side dictionary updates (instant) against server-rendered sections (stale until full request). The switcher updated cookie + client state but never re-rendered server components.
Two render sources (client context + server components) sharing one cookie, with the switcher updating only one side.
setLocale triggers router.refresh(); single cookie contract read identically by layout/server-i18n/client provider; parity + script-change regression tests added.
Locale ≠ direction, and hybrid render trees need ONE transition that refreshes BOTH sides. Also: audit bundles — a dev-only credential hint had shipped to production inside translations.
During generation, "View Article" opened an empty shell.
"postId exists means there's something to see." The pipeline reserves an empty placeholder post up-front, so postId was true from millisecond one.
Inspected what the API actually exposed (nothing about readiness) versus what the DB contained (status='draft', empty content).
UI action gated on identifier existence instead of business state.
API exposes postStatus+postHasContent read live; pure canViewArticle() gate with a 7-case matrix test; verified end-to-end by flipping a published article to empty-draft and back through the admin API — gate hid, then restored with content intact.
Gate actions on business state delivered by the backend. IDs are pointers, not predicates.
Voice Agent settings blank when no config row existed; when present, full of provider/model fields the runtime ignored.
"The form just needs wiring up." Reading the service showed which fields the reply pipeline ACTUALLY consumes: ragEnabled, systemPrompt, temperature — nothing else.
Grepped every consumer of the config object; confirmed STT/TTS run entirely in-browser via Web Speech API and the LLM resolves per-purpose from model configuration.
UI mirrored a hypothetical architecture (external STT/TTS + selectable models) instead of the real one (browser APIs + purpose-routed LLM). Plus null-config rendered literally nothing.
Honest panel: capability status (browser Web Speech, languages EN/FA, live resolved engine) + exactly the three real controls; whitelist PATCH; contract test asserting the exposed key set equals the consumed set; defaults so the panel never blanks.
Settings UIs must expose the intersection of what users can change and what the system reads. Everything else is fiction that erodes trust — and a contract test can enforce honesty forever.