[mforce]

Closes #603.

What

provision-account gains an optional --timezone. #537 closed assuming this flag existed; it did not, so a farm always started in UTC and its first day of data was recorded against the wrong zone until the Owner reached Settings.

provision-account --name "Example Farm" --slug example-farm \
  --owner-email owner@example.com --locale en-US --currency USD \
  --timezone Asia/Manila

Omitting the flag keeps the previous behaviour exactly: the farm starts in UTC and its Owner sets the zone in Settings.

Validation, and where

Validated in AccountProvisioner.Validate with FarmSettingsRules.IsKnownTimeZone — the same predicate UpdateFarmSettingsValidator uses, so the CLI cannot commit a zone Settings would reject. It runs before any write, which is what the issue asks for: #264's clock fails closed, so a farm committed with an unresolvable zone renders no dates at all.

The rule is stricter than a bare FindSystemTimeZoneById: it also requires a real IANA id, so PST and asia/manila are refused.

Account.DefaultTimeZoneId replaces the two "UTC" literals (the property initialiser and the provisioner default) that had to agree.

Tests

ProvisionAccountCommandTests: 11 pass.

• --timezone Asia/Manila commits that zone, and the committed value resolves through TimeZoneInfo.FindSystemTimeZoneById.
• No flag still commits UTC.
• Three unresolvable zones write nothing and name Provision.TimeZoneInvalid.
• The malformed-option theory keeps --time-zone (still not an option), a valueless --timezone, and a duplicated one.

The semantic cases live in their own test rather than the malformed-option theory, because that theory asserts the farm code was never echoed — true for option shape errors, which are caught before the echo, but not for a semantic rejection, which happens in the provisioner after it, exactly as an invalid --locale does today.

Four mutants, each red on the assertion that names it:

Mutant	Red on
IsKnownTimeZone weakened to a blank check	the three unresolvable zones
Flag ignored, always UTC	commits-that-zone, plus the three
--timezone not forwarded from the CLI	same four
--timezone dropped from AllowedOptions	same four

A first attempt at mutant 1 (if (false)) did not compile under warnings-as-errors and its "green" came from a stale binary; redone with a weakening that compiles.

Guard that fired

TenantBypassRealTreeTests anchors allowlist entries on the full method signature, so adding a parameter made the ProvisionAsync entry both unexcused and stale. Entry updated. This is a live instance of the brittleness #632 proposes to remove.

Docs

The AGENTS #264 bullet and docs/decisions/264-farm-timezone.md both stated the zone is set in Settings and not at provisioning time. That is what this PR changes, so both are amended rather than left contradicting the code. The decision record also notes this does not reinstate the Seed:TimeZoneId config lever #283 retired, and why a per-farm CLI argument is a different thing from a boot-time config key.

Runbook: the example, guidance on when to state the zone, and a Provision.TimeZoneInvalid failure row.

Full suite

2284 pass. One unrelated flake in OtlpSubprocessExporterTests appeared in one full run: it passes on repeat, passes on the stashed tree, and shares nothing with this change.

Summary by CodeRabbit

• New Features

  • Farm provisioning now supports an optional IANA timezone.
  • Supplied timezones are validated before account creation and saved to the new farm.
  • Provisioning without a timezone continues to default to UTC.

• Documentation

  • Updated provisioning guidance and decision records with timezone configuration, validation, defaults, and troubleshooting steps.

• Bug Fixes

  • Invalid or unresolvable timezones are rejected without writing changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: a495fce6-df75-4910-900b-61373e70e977

📥 Commits

Reviewing files that changed from the base of the PR and between 1b5d398 and de1cd43.

📒 Files selected for processing (8)

• AGENTS.md
• docs/decisions/264-farm-timezone.md
• docs/runbooks/provisioning-a-new-farm.md
• src/Cluckwork.Api/Cli/ProvisionAccountCliCommand.cs
• src/Cluckwork.Domain/Accounts/Account.cs
• src/Cluckwork.Infrastructure/Identity/AccountProvisioner.cs
• tests/Cluckwork.Api.IntegrationTests/ProvisionAccountCommandTests.cs
• tests/Cluckwork.Application.Tests/TenantBypass/Data/tenant-bypass-allowlist.json

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

Farm provisioning now accepts an optional IANA timezone. The CLI passes the value to account provisioning, which validates it before writing. Omitted values default to UTC. Tests and provisioning documentation cover validation, persistence, and verification.

Changes

Farm timezone provisioning

Layer / File(s)	Summary
Timezone option and default contract src/Cluckwork.Api/Cli/ProvisionAccountCliCommand.cs, src/Cluckwork.Domain/Accounts/Account.cs	The CLI accepts --timezone and passes it to provisioning. Account.DefaultTimeZoneId centralizes the UTC default.
Timezone validation and account persistence src/Cluckwork.Infrastructure/Identity/AccountProvisioner.cs, tests/Cluckwork.Application.Tests/TenantBypass/Data/tenant-bypass-allowlist.json	Provisioning validates known IANA timezones before writes, defaults omitted values to UTC, and stores the validated timezone on the account. The recorded method signature includes the new parameter.
Integration coverage and operational documentation tests/Cluckwork.Api.IntegrationTests/ProvisionAccountCommandTests.cs, docs/decisions/264-farm-timezone.md, docs/runbooks/provisioning-a-new-farm.md, AGENTS.md	Tests cover malformed options, invalid values, committed timezones, and the UTC default. Decision, runbook, and agent documentation describe the updated provisioning behavior.

Estimated code review effort: 2 (Simple) | ~15 minutes

Merge Risk: ⚪ Minimal · up to de1cd

Provisioning now accepts an optional validated IANA timezone while retaining UTC when omitted; invalid values are rejected before account creation. The documented and tested behavior is ready to merge.

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant ProvisionAccountCliCommand
  participant AccountProvisioner
  participant Account
  Operator->>ProvisionAccountCliCommand: provide optional --timezone
  ProvisionAccountCliCommand->>AccountProvisioner: pass timeZoneId
  AccountProvisioner->>AccountProvisioner: validate or default timezone
  AccountProvisioner->>Account: persist TimeZoneId

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (4 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding an optional --timezone argument to provision-account. It also uses a conventional commit format.
Description check	✅ Passed	The description explains the change, motivation, validation behavior, tests, documentation updates, and full-suite results. It omits the template's explicit Checklist section, but the description is o…
Linked Issues check	✅ Passed	The changes satisfy issue #603 by adding the optional --timezone flag, validating the timezone before writes, preserving the UTC default, storing the selected timezone at creation, and updating relate…
Out of Scope Changes check	✅ Passed	The code, tests, documentation, runbook, decision record, and tenant-bypass allowlist changes directly support issue #603 and the stated provisioning objective. No unrelated changes are evident.

Full details: Docstring Coverage

Explanation

Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/provision-account-timezone

---

_{Comment @coderabbitai help to get the list of available commands.}