# Default turn-doc diffs to `@pierre/diffs`

Completed on May 23, 2026 at 6:47 PM ET.

## Summary

Updated repository turn-documentation rules to prefer `@pierre/diffs` for diff snippets, added a documented fallback path, and included the package/lock updates needed for consistent local usage.

## Changes Made

- Edited `AGENTS.md` to add a default diff-format policy for turn docs.
- Updated the minor-update template bullet for `Code diffs` with explicit `@pierre/diffs` default plus fallback wording.
- Updated required section `Relevant Diff Snippets` with the same default-and-fallback wording.
- Added `@pierre/diffs` to root `package.json` dependencies and synced `bun.lock`.

## Context

The existing guidance required a diff section but did not explicitly standardize on a single rendering tool. This change aligns turn-doc expectations around one default tool while preserving an escape hatch when tooling is unavailable.

## Important Implementation Details

- The policy is intentionally a preferred default, not a hard requirement.
- Fallback usage is constrained to real tool/blocking errors and must be labeled with a reason.
- No runtime application behavior was changed; this is workflow/documentation and dependency-surface work.

## Relevant Diff Snippets

`@pierre/diffs` is now the repository default for this section.

    --- AGENTS.md
    +++ AGENTS.md
    @@
    +For diff content in turn documentation (including "Code diffs" and "Relevant Diff Snippets"), use `@pierre/diffs` output by default.
    @@
    -- **Code diffs**
    +- **Code diffs** (use `@pierre/diffs` output by default; if unavailable, include a clearly labeled plain diff/code block and note why)
    @@
    -5. **Relevant Diff Snippets**
    +5. **Relevant Diff Snippets** (render with `@pierre/diffs` output by default; if unavailable, include a clearly labeled plain diff/code block and note why)

    --- package.json
    +++ package.json
    @@
    +  "dependencies": {
    +    "@pierre/diffs": "^1.2.2"
    +  }

## Expected Impact for End-Users

- Future turn docs should have more consistent and readable diff presentation.
- Contributors have clearer guidance for fallback behavior when the preferred renderer cannot be used.

## Validation

- Verified policy text appears in all required AGENTS locations for diff guidance.
- Ran `bun install --frozen-lockfile` and confirmed lockfile consistency with no changes.
- Confirmed repository is clean and branch is up to date after push.

## Issues, Limitations, and Mitigations

- This change standardizes policy but does not retroactively update old turn docs.
- Actual visual rendering still depends on environment/tool availability; fallback instructions mitigate this.

## Follow-up Work

- Optionally add a tiny helper script/example to generate `@pierre/diffs` HTML snippets directly for turn docs.