spec: remediate cross-repository documentation consistency

[warp-agent-staging]

Summary

Adds the durable product and technical specification for the cross-repository documentation consistency remediation. The spec accounts for all 24 audit findings, separates deterministic corrections from owner-gated decisions, defines the missing_docs consistency extension, and blocks production changes until approval.

This revision incorporates independent review of cloud attachments, billing-contract boundaries, CLI migration milestones, CLI help, the missing-docs baseline, and Free-tier evidence.

Changes

• Records required behavior, evidence, owners, and dispositions for 19 contradictions and 5 content issues.
• Corrects cloud attachment behavior for footer, paste, drop, and CLI input; includes the stale --attach help and verified 25-file and 10 MB limits.
• Treats billing resolver code as private reviewer evidence and requires Billing and Product to approve user-actionable public semantics for findings 2–4.
• Keeps the September 30 command-support milestone separate from the October 6 naming and wrapper transition.
• Requires classification of all ten current surface deltas before maps, docs, OpenAPI, or the committed snapshot change.
• Uses “up to 5,000 files per repository” for the Free entitlement and current tier evidence ranges.
• Preserves the verified SSH wording and existing privacy, ZDR, Fireworks, Windows fish, and Ventura owner gates.

Unverified claims

• Billing and Product must define the public charge and entitlement contract for findings 2–4.
• Product Marketing and Billing must confirm coordinated public pricing copy for the Free indexing and harness entitlements and Add-on Credits terminology.
• API and agent-tooling owners must publish or defer six API routes and one server tool before snapshot regeneration.
• Customer-data training, Free telemetry opt-out, AI availability, retention, and ZDR provider language require Product, Privacy, Security, and Legal approval.
• Neither CLI milestone can change without CLI-owner confirmation; command parity and redirects also require CLI-owner review.
• Official MSYS2 fish support requires Terminal and Support confirmation.

Validation

• Passed: 24 ordered findings with exactly one approved status each.
• Passed: all 90 concrete cited repository paths exist.
• Passed: requested wording invariants and stale-phrase exclusions.
• Passed: git diff --check.
• Passed: npm run typecheck with 0 errors.
• Passed: 19 reviewer-resolution tests and 17 release-check tests.
• Reconfirmed baseline: audit_docs.py --diff reports exactly ten surface changes: two removed flags, one added dogfood flag, one added server tool, and six added API routes.
• Expected baseline failure: 17 of 18 test_audit_docs.py tests pass; test_diff_against_committed_snapshot_is_current reports the same ten unreconciled surface changes. The spec prohibits a snapshot-only refresh.
• Known repository baseline: npm run build reaches static prerendering, then /_llms-txt/support.txt overflows hast-util-to-text; this reproduces under Node 22 and Node 24 and is outside the spec content path.

Documentation risk

Risk: engineering-review-required
Rationale: The specification records billing, privacy, API, CLI, and support claims across multiple owned systems.
Source files consulted: specs/cross-repository-documentation-consistency-remediation.md@7ef3f3671350ec0417acc0ea77194d0c79e6c749, warp/app/src/ai/agent_sdk/driver/attachments.rs@43eae5e082db7991da89388d57125df6ae9a130d, warp-server/logic/ai/ai_usage/cost_resolution.go@09ac64fc85ea55a9da74201d5b4b5da02fc077d8
Engineering review status: pending
Docs override: none

Approval gate

Please approve this revised specification before implementation starts. Approval authorizes the documented deterministic corrections and detector design. It does not supply the owner-gated decisions listed above.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 24, 2026 11:24pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.