feature request(docs): show delta in PR

repo split to be discussed

---

# Add documentation delta reporting to PR previews

## Summary

Extend the documentation pipeline so docs.yml generates a delta report, while docs-publish.yml remains the only workflow that writes PR comments.

The existing preview comment will be updated to include:

- Needs added, removed, or modified.
- Full field-level diffs for modified needs.
- Direct old/new documentation links when available.
- Changed rendered HTML pages with old/new links.

Individual entries are listed only when each category contains at most 15 items. Larger categories receive counts only.

## Implementation Changes

- Add a tested docs_delta tool to docs-as-code, exposed through the standard generated docs target, for example bazel run //:docs_delta.
- The tool accepts:
- Published baseline documentation directory.
- Current _build directory.
- Base and PR documentation URLs.
- Output report path.

- Compare needs by ID:
- Added: only in the PR build.
- Removed: only in the baseline.
- Modified: present in both but differing after excluding known volatile fields.

- Use each need’s docname to construct direct rendered-document links.
- Compare rendered .html files using normalized content to ignore known volatile build metadata.
- Make docs.yml:
- Build the PR documentation as it does today.
- Retrieve the published main documentation from gh-pages when running for a pull request.
- Run docs_delta.
- Upload the delta report as a separate artifact.
- Continue granting only read permissions and never call the GitHub comments API.

- Make docs-publish.yml:
- Download the delta artifact for PR contexts.
- Find the existing preview comment.
- Create or update that comment with the preview link and generated delta report.
- If the baseline is unavailable, include an explicit “delta unavailable” notice while still publishing and commenting with the preview link.
- Preserve current behavior for branch, tag, release, and merge-queue publications.

## Test Plan

- Unit-test needs comparison for added, removed, modified, unchanged, and field-level changes.
- Test the 15-item threshold independently for needs and HTML pages.
- Test old/new link generation for modified entries and one-sided links for added/removed entries.
- Test HTML normalization against timestamp and generated-metadata changes.
- Test missing baseline behavior.
- Add an integration-style test using fixture baseline/current documentation trees and assert the generated Markdown report.
- Update docs.md to document the generated delta and the combined preview comment.

## Assumptions

- The existing needs.json output and rendered _build directory are the comparison inputs.
- The published main directory on gh-pages is the baseline.
- Needs and rendered-page lists are summarized independently; one category exceeding 15 does not suppress detailed output in the other.
- The existing preview comment marker remains the comment identity key, so no additional PR comment is created.

Start by reading docs.yml and docs-publish.yml, then inspect the existing documentation build outputs, needs.json, _build directory, and preview-comment handling. Trace how docs.md documents the current preview flow. Done means a tested docs_delta entry point produces the specified Markdown report, docs.yml uploads it, docs-publish.yml incorporates it without changing non-PR publication behavior, and docs.md is updated.

Written by the indexing model from the issue text.