feat(docs): add opt-in mask-pii setting for Ask AI

[devin-ai-integration]

Description

Linear ticket: Refs

Adds an explicit, opt-in mask-pii setting to the Ask AI (ai-search / deprecated ai-chat) block in docs.yml. PII masking is off by default; it is only enabled when a customer sets mask-pii: true. The masking itself happens client-side in the docs bundle (separate fern-platform PR) — this PR only threads the new setting from docs.yml through the CLI into the docs config sent to FDR.

ai-search:
  mask-pii: true   # absent / false => masking disabled (default)

Config flow:

docs.yml (mask-pii)
  -> AIChatConfig zod schema ("mask-pii")
  -> generated SDK AiChatConfig (maskPii <-> "mask-pii")
  -> ParsedDocsConfiguration.aiChatConfig.maskPii
  -> DocsDefinitionResolver -> DocsV1Write.aiChatConfig.maskPii

Changes Made

• Add "mask-pii": optional<boolean> to the docs-yml source definition (fern/apis/docs-yml/definition/docs.yml).
• Add "mask-pii" to the AIChatConfig zod schema in DocsYmlSchemas.ts.
• Regenerated docs-yml SDK types + JSON schema (pnpm docs:generate, pnpm jsonschema): AiChatConfig now carries maskPii mapped to/from the mask-pii YAML key.
• Propagate maskPii through DocsDefinitionResolver into the FDR write config.
• Unit tests for the schema: absent -> undefined (off by default), explicit true/false preserved.
• Unreleased changelog entry (feat).
• Updated README.md generator (if applicable) — n/a

Testing

• Unit tests added/updated — @fern-api/configuration (DocsYmlSchemas.test.ts) passing.
• pnpm docs:generate + pnpm jsonschema produce no unexpected diffs; hand-written generated types match codegen output.
• pnpm format:check and turbo compile (configuration, configuration-loader, docs-resolver) + docs-resolver tests passing.

Link to Devin session: https://app.devin.ai/sessions/7c9f531bc08b4a7f8c7eb1282d1aa4a8

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[nitpickybot]

AI Review Summary

The PR threads a new opt-in mask-pii setting from docs.yml through to the FDR write config. There's a mismatch between the zod schema (which uses the raw YAML key mask-pii) and the resolver code that reads a camelCased maskPii, which likely breaks the feature at runtime.

• 🔴 1 critical issue(s)
• 🔵 1 suggestion(s)

[nitpickybot]

🔴 critical

this.parsedDocsConfig.aiChatConfig originates from the zod AIChatConfig schema, where the field is "mask-pii", not maskPii. Unless there's a serialization step between the zod-parsed config and parsedDocsConfig that converts to camelCase (the generated SDK serialization does, but the zod schema doesn't), this.parsedDocsConfig.aiChatConfig.maskPii will always be undefined and the setting will silently never propagate. Verify which type parsedDocsConfig.aiChatConfig actually is and use the matching key.

[nitpickybot]

🔵 suggestion

Changelog says the setting is under ai-chat, but the PR description says it applies to ai-search (with ai-chat deprecated). Point users at the current block name to avoid confusion.

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-07-13T05:08:13Z).

Fixture	main	PR	Delta
docs	241.5s (n=5)	228.1s (35 versions)	-13.4s (-5.5%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-07-13T05:08:13Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-07-13 21:15 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-07-13T05:08:13Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	76s (n=5)	115s (n=5)	68s	-8s (-10.5%)
go-sdk	square	139s (n=5)	285s (n=5)	134s	-5s (-3.6%)
java-sdk	square	226s (n=5)	267s (n=5)	202s	-24s (-10.6%)
php-sdk	square	61s (n=5)	85s (n=5)	51s	-10s (-16.4%)
python-sdk	square	135s (n=5)	241s (n=5)	128s	-7s (-5.2%)
ruby-sdk-v2	square	94s (n=5)	124s (n=5)	82s	-12s (-12.8%)
rust-sdk	square	169s (n=5)	176s (n=5)	155s	-14s (-8.3%)
swift-sdk	square	58s (n=5)	433s (n=5)	52s	-6s (-10.3%)
ts-sdk	square	127s (n=5)	128s (n=5)	116s	-11s (-8.7%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-07-13T05:08:13Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-07-13 21:17 UTC