docs: address daily-audit findings (terminology, surface-map hygiene, --mcp well-known-id doc)

[warp-agent-staging]

Rework changes

• Rework cycle 3 — 2026-08-26 (a verification review rejected rework cycle 2 for two blocking issues):
  1. Style-lint scanner still wasn't context-aware (the original formal-review requirement from GitHub PR review 4979931272 — never actually implemented in prior cycles, only worked around by declining the findings). check_product_casing and check_deprecated_terms in .agents/skills/style_lint/style_lint.py only skipped a line that itself started with a backtick/fence marker, so a multi-line fenced code block's interior lines, and a Markdown link/image destination on an otherwise-prose line, were both still scanned as prose. Added a shared _strip_markdown_destinations helper and fenced-code-block tracking (in_code_block, matching the pattern already used by check_oz_terms) to both checks, so Blocklist inside the literal image filename in code/code-review.mdx:64 (Blocklist-with-review-changes.png) and MacOS inside the literal executable paths in sending-us-feedback.mdx:75,78 (/Applications/Warp.app/Contents/MacOS/stable) are no longer flagged, while a genuine prose hit is still caught correctly. Added regression coverage in a new test_context_aware_terminology.py (a fenced-code-block case and a Markdown-link-destination case that must NOT flag, plus a normal prose case that must still flag, for both checks). Confirmed via style_lint.py --all that exactly these 3 findings are gone and diffed the full before/after issue list to confirm no new findings appeared.
  2. 38 duplicate feature_surface_map.md entries left unresolved by the main-merge (commit 8247468). The merge kept both branches' independent additions as literal duplicates: 36 /factory*//factory-files/*//factory-alias/*//factory-setup/* API-endpoint internal-ignore lines, and 2 feature-flag ignore lines (OrchestrationUnifiedStack, WaitForEventsParentRegistration). Removed the duplicate copies, keeping whichever copy had the fuller/more specific comment in each case (the original per-route/per-flag annotations, over the generic bulk-add block's comment). Confirmed via audit_docs.py --diff that zero map_hygiene duplicate-entry findings remain for these entries.
  • Also corrected this PR body's Verification section below, which previously implied the fenced-code/link-destination handling was already implemented — it wasn't; it had only ever been documented as a "declined finding," never the linter fix the reviewer actually asked for. Fixed a duplicated ## Summary heading while editing this body.
• Additional casing fix (direct requester feedback, not a review cycle): restored capitalization of Blocks, Tab Configs/Tab Config, and Launch Configuration wherever the header-case auto-fix had lowercased them across quickstart.mdx, terminal/windows/tab-configs.mdx (6 headings), and terminal/sessions/launch-configurations.mdx (2 headings). Added all of these to PROPER_FEATURE_NAMES in style_lint.py and a matching terminology.md entry for Launch Configuration (Blocks/Tab Configs were already documented there). Re-ran the corpus-wide scan to confirm no other instances remained.
• Rework cycle 1 (formal code review, "Request changes"): fixed two more sentence-boundary regressions the review caught — factories/integrations/gitlab.mdx ("Factory definitions..." after a stripped MDX comment) and the pricing-faqs.mdx two-question FAQ heading ("...yet. How does billing work?"). Hardened style_lint.py at the source for both bug classes (MDX-comment-hidden sentence boundaries in check_factory_proper_noun, and multi-sentence headers in check_header_case/_to_sentence_case via a new _sentence_start_indices helper), added regression tests, and re-ran the corpus-wide scan to confirm no other files were affected.
  Addressed direct requester feedback from the Slack thread:
• Restored capitalization of Full Terminal Use, Computer Use, Zero Data Retention (ZDR), and Single Sign-On (SSO) everywhere the header-case auto-fix had incorrectly lowercased them (these weren't caught in the original hand-verification pass). The bare SSO acronym itself was already preserved correctly everywhere; only the spelled-out "Single Sign-On" phrase needed restoring.
• Made this durable: added all four to PROPER_FEATURE_NAMES in .agents/skills/style_lint/style_lint.py (the header-case sentence-case exception set) and added matching entries to .agents/references/terminology.md, so future style_lint --fix runs stop flagging/fixing them. Re-ran style_lint.py --all and the style_lint test suite to confirm no new false positives.
• Light polish pass: renamed the new --mcp well-known-id subsection heading to "Passing MCP servers by well-known id" to match the parallel heading style used by its sibling sections on the same page.
• Rework cycle 2 — 2026-08-26 (fresh final-pass content review against docs messaging/terminology guidelines, benchmarked against how Anthropic/Claude Code, OpenAI/Codex, Cursor, Devin, and Factory document similar concepts): addressed 12 findings.
  1. Fixed a real word-boundary bug in check_product_casing (.agents/skills/style_lint/style_lint.py): it used line.find(wrong) with no boundary check, so the "agent mode" → "Agent Mode" rule matched inside "agent model" and corrupted agents/cli/reference.mdx's /model row into "Switch the base Agent Model". Hardened matching with lookaround-based word boundaries (plain \b...\b doesn't fully fix this either, since it fails on terms ending in punctuation like "A.I."), added a regression suite (test_product_casing_word_boundary.py), and restored the doc text to "agent model".
  2. Restored "Warp Terminal" in enterprise/index.mdx's three-products bullet — the exact "specifically distinguishing" case PRODUCT_CASING's own comment says should be exempt, but the blind substring replace has no such context awareness. Fixed only this instance; see the structural note below.
  3. Restored "Team" capitalization in a pricing-faqs.mdx FAQ heading to match every other "Team" reference in that entry.
  4. Restored "Block Sharing" capitalization in guides/agent-workflows/understanding-your-codebase.mdx (named feature page).
  5. Restored "Bring Your Own LLM (BYOLLM)" capitalization in security-overview.mdx and pricing-faqs.mdx. Added it to PROPER_FEATURE_NAMES + a terminology.md entry, following the ZDR/SSO/Full Terminal Use/Computer Use pattern; re-scanned the corpus for other instances (none found).
  6. Reverted three undisclosed ## → ### heading-level promotions for "Zero Data Retention (ZDR)" (security-overview.mdx, team-managed-keys-and-endpoints.mdx, byollm-aws-bedrock.mdx) that had orphaned sibling sections or de-nested the heading from its true parent section.
  7. Reverted an undisclosed ## → heading-level promotion for "MCP (Model Context Protocol)" in getting-started-developers.mdx that had pulled it out of the numbered "3. Set up key features" section, breaking the page's numbered onboarding flow.
  8. Restored "Bitbucket Data Center / Server" capitalization (Atlassian's official edition name) in platform/integrations/bitbucket.mdx.
  9. Restored "Workload Identity Pool and Provider" / "Workload Identity Federation" capitalization (official GCP terms) in platform/integrations/cloud-providers.mdx.
  10. Restored "API key Secret" capitalization (Kubernetes resource kind) in platform/self-hosting/managed-kubernetes.mdx.
  11. Restored "Direct backend" capitalization in platform/self-hosting/managed-direct.mdx.
  12. For findings 8–11: added "Bitbucket Data Center", "Workload Identity Pool and Provider", "Workload Identity Federation", and "Direct backend" to PROPER_FEATURE_NAMES + matching terminology.md entries, with regression coverage in a new test_proper_feature_names_third_party.py. See the second structural note below.
  13. Checked the --mcp resolution-order list in reference/cli/mcp-servers.mdx against warp/crates/warp_cli/src/mcp.rs — main had independently superseded this exact section (PR docs(mcp): document well-known managed integration ids #599, "document well-known managed integration ids") with a more accurate rewrite while this PR was in flight, so the merge took main's version as authoritative rather than re-deriving order from the older framing this PR had been carrying.
  • Structural note for the requester (checker limitation, item 2): PRODUCT_CASING's "Warp Terminal" → "Warp" rule is a blind substring replace with no way to detect the "unless specifically distinguishing" exception its own comment names. It will keep flagging legitimate uses like the enterprise three-products list. Not fixed here (a context-aware rule engine is out of scope) — flagging as a real limitation worth tracking.
  • Structural note for the requester (checker limitation, items 8–11): style_lint.py's proper-noun protection (PROPER_FEATURE_NAMES) is scoped to Warp's own product names by design. It does not generalize to third-party/technical proper nouns, so any new Bitbucket/GCP/Kubernetes-style term will keep getting silently mis-cased by --fix until someone adds it as a named exception, one at a time. This is a structural limitation, not something to over-engineer a general fix for.
  • Re-ran style_lint.py --all, the full style_lint regression suite (including the two new test files), the missing_docs unit tests, and npm run build.

Summary

Addresses a low-risk, mechanical subset of findings from the daily docs-audit digest (missing_docs, style_lint, check_for_broken_links), per REV-38:

1. Terminology cleanup via style_lint.py --fix: blocklist → denylist (4/4 — see rework cycle 3 for the last one), MacOS → macOS (0/2 legitimate — both are literal executable paths in fenced code, now correctly left un-flagged by a context-aware scanner as of rework cycle 3), ambient agent → cloud agent(s) (4/4), bare "Factory" → factory (1/1), and 93 header-case (Title Case → sentence case) findings corpus-wide.

2. Surface-map hygiene in .agents/skills/missing_docs/references/feature_surface_map.md:

   • Repointed the AgentMode/AgentOnboarding GA-flag entries off their deleted doc paths to where that content now lives (agents/index.mdx and the installation/setup quickstart's "Log in to Warp" section).
   • Added a FactoryMcp mapping (factories/factory-mcp.mdx) and a WellKnownMcpIds mapping (see item 3).
   • Added OrchestrationUnifiedStack/WaitForEventsParentRegistration to the internal-flags ignore list — both are internal client-side orchestration event-delivery plumbing with "no user-visible behavior change" per their design specs (warp/specs/QUALITY-928/TECH.md, warp/specs/QUALITY-919/TECH.md).
   • Bulk-added internal entries (with a comment) for the 36 undocumented /factory*, /factory-files/*, /factory-alias/*, and /factory-setup/* API routes — Factory-UI-only backend routes, not part of the released public Oz Agent API.
   • Refreshed references/surface_snapshot.json via --update-snapshot.
   • Rework cycle 3: the main-merge left both of the above additions duplicated (36 API-route lines + the 2 feature-flag lines); deduped down to one line each, keeping the fuller comment.

3. New doc content: documented the --mcp <well-known-id> CLI shorthand (FeatureFlag::WellKnownMcpIds, shipped GA — warp/crates/warp_cli/src/mcp.rs:88) in reference/cli/mcp-servers.mdx.

A note on the style_lint --fix diff

I hand-verified the full auto-fix diff (per the ticket's explicit instruction) rather than trusting it blindly, and found the auto-fixer has several real bugs beyond this ticket's scope to fix in the tool itself, so I corrected the affected content instead:

• It doesn't respect fenced code blocks, so it rewrote a literal macOS app-bundle path (Contents/MacOS/ → Contents/macOS/, which would have broken the documented command) and edited the wording of a verbatim third-party license text (CDLA Permissive 2.0) reproduced inside a fenced code block.
• Its header-case heuristic doesn't know about proper nouns/product names, so it lowercased Warp, Git, GitHub, GitLab, Slack, Jira, Linear, Figma, Rust, Docker, Playwright, ChatGPT, Tailwind, Markdown, Finder, Vertex AI, Gemini Enterprise, and Model Context Protocol in dozens of headers. I restored proper-noun casing while keeping the legitimate sentence-case corrections.
• Its ui-backtick check misidentified non-UI identifiers (a keyboard key, file extensions like .dmg/.command, and JSON/config field names like status_message/detail/imagePullSecrets) as clickable UI elements and bolded them; I reverted those to backticks per the style guide ("Backticks — code, commands, file paths ... config values").
• apply_fixes replaces the first textual occurrence of a fix's exact string anywhere in the file rather than the specific flagged line, so when the same backtick phrase appeared more than once in a file, the fix landed on the wrong occurrence. Reverted the one instance this caused (platform/self-hosting/troubleshooting.mdx).

Declined findings (kept as-is, not force-fixed)

• support-and-community/privacy-and-security/privacy.mdx:85,87 — declined initially considered, but on inspection these table rows are literal telemetry event descriptions (prose, not code), so they were updated to denylist for consistency with the rest of the same "Exhaustive telemetry table" (which already uses Denylist/Allowlist elsewhere).

No longer declined as of rework cycle 3: code/code-review.mdx:64 (Blocklist in an image filename) and sending-us-feedback.mdx:75,78 (MacOS in a fenced executable path) were previously left as "declined findings" here instead of being fixed at the source, which is exactly what GitHub PR review 4979931272 rejected this PR for. Rework cycle 3 made style_lint.py's check_product_casing and check_deprecated_terms skip fenced code blocks and Markdown link/image destinations, so these two are now genuinely fixed (the scanner no longer flags non-prose text) rather than accepted exceptions. See "Rework cycle 3" above.

Out of scope (per the ticket)

The broader 29-page pre-rename terminology sweep, the ~790 unrecognized-term glossary suggestions, the 217 screenshot-width findings, the 8 link-anchor issues, the Oz → Automation Platform rename migration, and 7 pre-existing/unrelated map-hygiene findings for stale /factory/scorers/* and /factory/autofix/* routes (renamed/removed in code, unrelated to this ticket's findings).

Verification

• python3 .agents/skills/style_lint/style_lint.py --all — the specific blocklist/MacOS/ambient-agent/bare-Factory/header-case findings from the ticket are gone. code-review.mdx:64 and sending-us-feedback.mdx:75,78 are fixed at the scanner level as of rework cycle 3 (see above), not merely declined — diffed the full before/after issue list and confirmed exactly these 3 findings disappeared with no new findings introduced. Config-only/pure-copy terminology edits are testing-exempt (config-only / pure-copy category per factory-verification — no automated regression test is meaningful for prose casing); the scanner fix itself is source code and ships with regression tests (test_context_aware_terminology.py).
• python3 .agents/skills/missing_docs/scripts/audit_docs.py --warp ../warp --warp-server ../warp-server --diff — AgentMode/AgentOnboarding no longer flagged as pointing at deleted paths, FactoryMcp/WellKnownMcpIds are mapped, OrchestrationUnifiedStack/WaitForEventsParentRegistration and the 36 routes are internal, and (as of rework cycle 3) zero map_hygiene duplicate-entry findings remain — the 38 duplicates left by the main-merge were deduped. Same testing-exempt category (map/snapshot bookkeeping) applies.
• npm run build passes.
• python3 .agents/skills/missing_docs/scripts/test_audit_docs.py and test_suggest_reviewers.py pass, except one pre-existing, unrelated failure (test_diff_against_committed_snapshot_is_current) caused by an out-of-band agents.custom_endpoints setting added to ../warp since the committed snapshot — reproduces identically on this branch's HEAD before this rework's changes and is unrelated to either blocking issue; leaving references/surface_snapshot.json untouched rather than bundling an unrelated snapshot refresh into this fix.
• python3 .agents/skills/style_lint/test_factory_proper_noun.py, test_hardcoded_var_exemptions.py, test_platform_determiner.py, test_header_case_sentence_boundary.py, test_product_casing_word_boundary.py, test_proper_feature_names_third_party.py, test_tone_checks.py, and the new test_context_aware_terminology.py all pass.
• This is docs-source content/data hygiene, not a rendered client UI change, so no computer_use verification was performed (per the ticket).

Originating thread: https://warpdotdev.slack.com/archives/C09BVK0PL3Y/p1787171871205549

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 26, 2026 11:00pm

[warp-for-oss]

@warp-agent-staging[bot]

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR performs broad docs terminology and sentence-case cleanup, updates missing-docs surface-map/snapshot data, and adds the --mcp well-known ID reference content. I found two diff-backed content regressions from the automated cleanup: one rendered sentence now concatenates after an MDX comment, and one FAQ heading lowercases a new sentence.

Concerns

• The GitLab factory integration sentence will render without a separating space/capital after the inline MDX comment.
• The billing FAQ heading changes “How” to lowercase after a sentence boundary.
• No security findings; no approved spec context was available.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-agent-staging]

Verdict: rejected

The current head is not ready to merge. The explicit style_lint.py --all acceptance criterion still fails for three listed findings:

1. src/content/docs/code/code-review.mdx:64 still emits Blocklist → denylist because the scanner treats the literal image filename Blocklist-with-review-changes.png as prose.
2. src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx:75 and :78 still emit MacOS → macOS even though both occurrences are inside fenced shell code and must remain literal executable paths.

Please make the scanner context-aware: track complete fenced code blocks for the casing/deprecated-term checks and exclude Markdown image/link destinations while retaining the associated human-visible prose. Then rerun python3 .agents/skills/style_lint/style_lint.py --all to verify these exact findings are absent.

I also verified the new --mcp <well-known-id> section against warp/crates/warp_cli/src/mcp.rs; its documented parsing and server-side resolution behavior are correct. GitHub CI is green.

This is a comment review because GitHub does not permit this account to request changes on its own PR.