docs(preferences): user-facing docs, changelog & e2e tests (IFC-2737)

[pa-lem]

What

Documentation, changelog, and e2e coverage for user preferences (IFC-2737, sub-task 6 of INFP-512).

• New user-facing page docs/docs/deploy-manage/user-management/managing-preferences.mdx — single page (Web + GraphQL tabs, mirroring managing-api-tokens.mdx) covering precedence (user → organisation default → browser), the date-format presets, setting personal preferences and organisation defaults, and the manage_global_preferences gate. Registered in the sidebar after "Managing API tokens".
• Changelog +ifc-2721-date-rendering.added.md — fills the gap: the four existing fragments cover setting preferences, but none covered the date/time rendering that this stack delivers.
• Python e2e tests tests/e2e/preferences/ — three flows: personal round-trip + clear-override, global-default inheritance, and the permission gate. Adds a shared select_combobox_option helper.

Authored via the writing-infrahub-docs skill; placement, pattern, and voice follow its rules. All facts grounded in the code on this branch (verified live against the running UI).

Stack

Stacked on #9930 (ple-prefs-date-display, IFC-2721) so preference-driven date rendering is real and the docs are truthful. Merge after #9930.

Reviewer attention

• Spec-vs-code drifts (docs use the code truth): the admin tab is "Global preferences" at /profile/global-preferences (the spec/PR feat(preferences): organisation defaults + global-permission gating #9871 said "Organisation defaults" / /organisation-defaults); the global row's owner key is the "__global__" sentinel (the spec said the Root node id).
• Vale was not run locally (not installed) — relying on CI. markdownlint + ruff are clean; the e2e tests collect.
• The global-default and permission e2e tests need the RBAC-seeded users (data_rbac); they run under shard_foundation in CI.
• Out of scope / open: the spec dev/specs/2026-04-user-preferences.md still lives only on ple-user-preferences, not on this stack — port separately if desired.

🖥️ Try it in the app (UI)

A. Set your personal preferences

1. In the left sidebar, click your account avatar (bottom) → Account settings. This opens /profile.
2. On the Profile tab, find the Preferences card (main column, next to your account details).
3. Date format — click the field (searchable dropdown). Options show as format patterns with a live "Example:" preview:
   • yyyy-MM-dd HH:mm — default (ISO_DATETIME)
   • yyyy-MM-dd'T'HH:mm:ssXXX (ISO_8601)
   • yyyy-MM-dd HH:mm:ss (ISO_DATETIME_SECONDS)
   • dd/MM/yyyy HH:mm (EU_DATETIME)
   • MM/dd/yyyy hh:mm a (US_12H)
4. Timezone — searchable dropdown of IANA names (e.g. America/New_York). Empty = "Automatic (inherited)".
5. Click Save (enabled once you change something).
6. Tip: re-selecting the value you already have clears your personal override (falls back to global/default).

B. See where it takes effect

The chosen format + timezone apply everywhere dates are rendered. Quick places to confirm:

• Open any object → metadata popover → "updated at" timestamp.
• Any DateTime attribute value on an object.
• The events / activity feed cards.
• Branch list date cells, tasks homepage, proposed changes.

Change the format in step A, then reload one of these — the timestamps pick up the new format/timezone immediately.

C. Global defaults (admins only)

1. Requires the manage_global_preferences permission — the default admin account has it.
2. Go to Account settings → the Global preferences tab (/profile/global-preferences).
3. In the Global date and time card, set Date format / Timezone (empty = "Automatic (browser default)"), then Save.
4. These become the defaults for every user who hasn't set their own — shown as source: GLOBAL in the GraphQL below.

---

🧪 Try it via GraphQL (GraphiQL sandbox)

Log in, then open the GraphiQL sandbox (Menu → GraphQL Sandbox). Paste the whole block below into the editor — because each operation is named, GraphiQL lets you pick which one to run.

# ── User Preferences: paste all of this into GraphiQL, then pick an operation

# 1. Baseline: your effective prefs (source = USER / GLOBAL / DEFAULT)
query EffectivePreferences {
  InfrahubEffectivePreferences {
    date_format { value source }
    timezone { value source }
  }
}

# 2. Set your own prefs (scope: USER) — re-run #1 after to see source flip to USER
mutation SetMyPreferences {
  InfrahubSetPreferences(scope: USER, date_format: US_12H, timezone: "America/New_York") {
    ok
    date_format
    timezone
  }
}

# 3. Your raw stored row (null = unset)
query MyRawPreferences {
  InfrahubUserPreferences {
    date_format
    timezone
  }
}

# 4. Reset one field to default (explicit null clears it; omit to leave unchanged)
mutation ResetMyDateFormat {
  InfrahubSetPreferences(scope: USER, date_format: null) {
    ok
    date_format
    timezone
  }
}

# 5. Read global defaults (needs manage_global_preferences)
query GlobalPreferences {
  InfrahubGlobalPreferences {
    date_format
    timezone
  }
}

# 6. Set global defaults (scope: GLOBAL, needs manage_global_preferences)
mutation SetGlobalPreferences {
  InfrahubSetPreferences(scope: GLOBAL, date_format: EU_DATETIME, timezone: "Europe/Paris") {
    ok
    date_format
    timezone
  }
}

Suggested order

1. Run EffectivePreferences — baseline, source should be DEFAULT.
2. Run SetMyPreferences, then re-run EffectivePreferences → source flips to USER.
3. Run MyRawPreferences to see exactly what's stored (null = unset).
4. Run ResetMyDateFormat, then re-run EffectivePreferences → date_format.source back to DEFAULT/GLOBAL, timezone stays USER.
5. (Admins) Run GlobalPreferences / SetGlobalPreferences — any user without a personal override then sees source: GLOBAL.

---

Reference — accepted values

date_format — enum DateFormat:

Value	Example
ISO_8601	2026-07-01T14:30:00+02:00
ISO_DATETIME	2026-07-01 14:30 (default)
ISO_DATETIME_SECONDS	2026-07-01 14:30:00
EU_DATETIME	01/07/2026 14:30
US_12H	07/01/2026 02:30 PM

timezone — plain string, any IANA name, e.g. "Europe/Paris", "UTC", "Asia/Tokyo".

Scopes: USER (self only, auth required) · GLOBAL (needs manage_global_preferences).

🤖 Generated with Claude Code

---

Summary by cubic

Adds user-facing docs for date/time preferences, a changelog for preference-driven rendering, and e2e tests for personal settings, global defaults, and the permission gate. Addresses IFC-2737.

• New Features
  • Docs page docs/docs/deploy-manage/user-management/managing-preferences.mdx covering resolution (user → global → browser), presets, Web/GraphQL flows, and the manage_global_preferences gate. Added to the sidebar after “Managing API tokens”.
  • Changelog changelog/+ifc-2721-date-rendering.added.md: the web UI now renders dates/times using effective preferences; stored values are unchanged.
  • E2E tests tests/e2e/preferences/*: personal round-trip + clear-override, global-default inheritance, and permission gate. Adds helper select_combobox_option.

^{Written for commit bf4d0e3. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 7 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds user-facing docs, changelog, and e2e tests for preferences; no behavioral changes or tradeoffs needing human judgment.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 7 files (changes from recent commits).

<sub>Shadow auto-approve: would auto-approve. Adds docs, changelog, e2e tests, and minor refactors. No behavior expansion, operational changes, or new public contracts. Bounded and clearly beneficial; Cubic verified implementation.

Re-trigger cubic</sub>