# `vale sync`'s destination isn't actually governed by this path -- it
# always writes under `$XDG_DATA_HOME/vale/styles` (undocumented, confirmed
# by testing: neither this file's discovery nor `--config` affects it). Set
# `XDG_DATA_HOME=$PWD/.vale-data` before running `vale sync`/`vale docs` so
# both commands agree on the same repo-local, gitignored location.
StylesPath = .vale-data/vale/styles
MinAlertLevel = warning
# `vale sync` reads this to know what to fetch from the Hub at CI time --
# styles are fetched fresh each run, not vendored into the repo.
Packages = Microsoft, alex, write-good

[*.md]
BasedOnStyles = Microsoft, alex, write-good

# --- Rules disabled against evidence from our own docs/ tree, not guessed ---
#
# Domain-vocabulary mismatches -- Microsoft's own product-terminology and
# audience assumptions don't fit this repo, not a style call:
#
# Wants "agent" replaced with "personal digital assistant" (Microsoft's
# assumed product context, not ours -- "agent" is core hyperhive vocabulary).
Microsoft.Terms = NO
# "URL" is exactly the right word for people configuring DNS and TLS;
# "use 'address' for a general audience" doesn't fit this audience.
Microsoft.GeneralURL = NO
# Empirically 100% redundant with write-good.Passive (kept, below): diffed
# the exact file:line:col locations each one flags on the full docs/ tree --
# 726/726 identical, zero difference either direction. Running both doubles
# the count for no extra coverage; keeping write-good's copy since
# write-good is the agreed base style, not a judgment that Microsoft's
# version is worse.
Microsoft.Passive = NO
# Fires on every spaced em-dash (' — ', ~2000 occurrences across docs/).
# Not a defensible "this repo chose this style" claim -- it's an incidental,
# emergent convention nobody deliberately picked, not a deliberate one worth
# defending. Disabled because retrofitting ~2000 existing occurrences is out
# of scope for a lint-adoption PR, not because the convention is correct.
Microsoft.Dashes = NO

# --- Wave 2 candidates: disabled for this initial rollout, not dismissed.
# Each needs either false-positive-rate data from a real pass, or an actual
# rewrite pass through the flagged headings/words -- both real follow-up
# work, not a permanent call:
#
# "Remove the adverb if it's not important to the meaning" needs a human
# judgment call per hit; revisit once we know the real false-positive rate.
Microsoft.Adverbs = NO
# Flags ordinary systems/ops vocabulary (destroy, crash, failure, hook) as
# "profane in some cases" -- miscalibrated for an engineering docs repo as
# shipped, but alex's other inclusive-language rules stay enabled below.
alex.ProfanityUnlikely = NO
# Fires on every form of "to be" (is/are/be/aren't/...); needs the same
# false-positive-rate pass as Adverbs before it's worth turning on for real.
write-good.E-Prime = NO
# Heading acronyms (MCP, CI, API, TLS, ...) are common in this tree, but
# that's not proof they're not worth spelling out -- e.g. "setting up
# transport encryption" instead of "setting up TLS" is a real improvement.
# Needs an actual rewrite pass through the flagged headings, not a blanket
# call either way.
Microsoft.HeadingAcronyms = NO

# --- Ruled on, not wave 2 -- disabled for good, not pending a follow-up pass ---
#
# Flags this repo's own consistent sentence-case heading convention
# ("### Current limitation: state-dir visibility lags topology") for not
# capitalizing after the colon. Same shape as Microsoft.Dashes above: a
# real house-style conflict, not a defect. Ruled to keep the house style.
Microsoft.HeadingColons = NO
# Checked every real hit on our docs/ tree: zero true positives. It fires
# on the word "percent" used as an identifier (`cpu.percent`, "percent
# resolver"), never on an actual spelled-out percentage. A rule with no
# observed true positive on this corpus isn't worth keeping enabled.
Microsoft.Percentages = NO