# Agent Integration Guide

This guide is for agentic coding partners that need to integrate the composite actions published by this repository.

## Source Of Truth

Pin all action references to a released tag (for example `@v1.2.0`) and keep all vociferate references on the same tag in a workflow.

Published composite actions:

- `https://git.hrafn.xyz/aether/vociferate@v1.2.0` (root action)
- `https://git.hrafn.xyz/aether/vociferate/prepare@v1.2.0`
- `https://git.hrafn.xyz/aether/vociferate/publish@v1.2.0`
- `https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0`
- `https://git.hrafn.xyz/aether/vociferate/decorate-pr@v1.2.0`

## Action Selection Matrix

Use this when deciding which action to call:

- Choose `prepare` when you need to update changelog/version files, commit, and push a release tag.
- Choose `publish` when a tag already exists and you need to create or update release notes/assets.
- Choose `coverage-badge` after tests have produced `coverage.out` and you need coverage artefacts uploaded.
- Choose `decorate-pr` to annotate pull requests with coverage information and unreleased changelog entries.
- Choose root `vociferate` for direct recommend/prepare logic without commit/tag/push behavior.

## Preconditions

Apply these checks before invoking actions:

- Checkout repository first.
- For prepare/publish flows that depend on tags/history, use full history checkout (`fetch-depth: 0`).
- Use `secrets.RELEASE_PAT` for release/tag/update operations (`prepare`, `publish`, `release`, `update-release`) so authenticated release changes can be pushed and published reliably.
- `release`, `update-release`, and `decorate-pr` run preflight API checks and fail fast when token credentials are missing or insufficient.
- Set required vars/secrets for coverage uploads:
  - `vars.ARTEFACT_BUCKET_NAME`
  - `vars.ARTEFACT_BUCKET_ENDPONT`
  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY`
  - `secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET`
- For externally visible changelog links, set `vars.VOCIFERATE_REPOSITORY_URL` to the server/base URL only.

## Changelog Format Guidance

Agents should keep `CHANGELOG.md` in a Keep a Changelog compatible structure because vociferate derives versions and release notes from headings.

Required conventions:

- Keep the top-level heading as `# Changelog`.
- Maintain an `## [Unreleased]` section.
- Keep the standard subsections under `Unreleased` in this order:
  - `### Breaking`
  - `### Added`
  - `### Changed`
  - `### Removed`
  - `### Fixed`
- Record releases with headings like `## [1.2.3] - YYYY-MM-DD`.
- Use bullet entries under subsections (for example `- Added new publish output`).
- Preserve or regenerate bottom reference links (`[Unreleased]: ...`, `[1.2.3]: ...`) instead of mixing inline heading links.

Semver behavior used by recommendation logic:

- `Breaking` or `Removed` entries trigger a major bump.
- `Added` entries trigger a minor bump.
- Otherwise recommendation falls back to a patch bump.

Minimal template:

```markdown
# Changelog

## [Unreleased]

### Breaking

### Added

### Changed

### Removed

### Fixed
```

## Minimal Integration Patterns

### 1. Full Release Workflow

```yaml
jobs:
  release:
    uses: https://git.hrafn.xyz/aether/vociferate/.gitea/workflows/release.yml@v1.2.0
    with:
      version: ${{ inputs.version }}
    secrets: inherit
```

### 2. Update Existing Release Tag

```yaml
jobs:
  release:
    uses: https://git.hrafn.xyz/aether/vociferate/.gitea/workflows/update-release.yml@v1.2.0
    with:
      tag: v1.2.3
    secrets: inherit
```

### 3. Coverage Badge Publication

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
```

### 4. Decorate Pull Request With Coverage and Changes

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_KEY }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.ARTEFACT_BUCKET_WRITE_ACCESS_SECRET }}
      AWS_DEFAULT_REGION: ${{ vars.ARTEFACT_BUCKET_REGION }}
      AWS_EC2_METADATA_DISABLED: true
    steps:
      - uses: actions/checkout@v4
      - name: Run tests with coverage
        run: go test -covermode=atomic -coverprofile=coverage.out ./...
      - id: badge
        uses: https://git.hrafn.xyz/aether/vociferate/coverage-badge@v1.2.0
        with:
          artefact-bucket-name: ${{ vars.ARTEFACT_BUCKET_NAME }}
          artefact-bucket-endpoint: ${{ vars.ARTEFACT_BUCKET_ENDPONT }}
      - name: Decorate PR
        uses: https://git.hrafn.xyz/aether/vociferate/decorate-pr@v1.2.0
        with:
          coverage-percentage: ${{ steps.badge.outputs.total }}
          badge-url: ${{ steps.badge.outputs.badge-url }}
```

## Inputs And Outputs Cheatsheet

### prepare

Common inputs:

- `version` (optional override)
- `version-file` (optional)
- `version-pattern` (optional)
- `changelog` (optional)

Primary output:

- `version` (resolved tag, for example `v1.2.3`)

### publish

Common inputs:

- `token` (optional, defaults to workflow token)
- `version` (optional if running from tag ref)
- `changelog` (optional)

Primary outputs:

- `release-id`
- `tag`
- `version`

### coverage-badge

Required inputs:

- `artefact-bucket-name`
- `artefact-bucket-endpoint`

Useful optional inputs:

- `coverage-profile` (default `coverage.out`)
- `summary-file` (append markdown summary)

Primary outputs:

- `total`
- `report-url`
- `badge-url`

### decorate-pr

Required inputs:

- `coverage-percentage` (0-100, typically from coverage-badge action)
- `badge-url` (SVG badge URL, typically from coverage-badge action)

Useful optional inputs:

- `changelog` (default `CHANGELOG.md`)
- `comment-title` (default `Vociferate Review`)
- `token` (defaults to workflow token)
- `enable-changelog-gate` (default `false`) - Enable changelog validation gate
- `changelog-gate-mode` (default `soft`) - `strict` or `soft` mode for gate
- `changelog-gate-required-for` (default `code,behavior,security,workflow,tooling`) - Change types requiring entries
- `changelog-gate-allow-docs-only` (default `true`) - Skip requirement for docs-only PRs
- `changelog-gate-docs-globs` (default `docs/**,**.md,**.txt,**.rst`) - Docs file patterns
- `changelog-gate-skip-labels` (default empty) - PR labels that bypass requirement

Primary outputs:

- `comment-id` - Comment ID
- `comment-url` - Comment URL
- `gate-passed` - Whether changelog gate validation passed
- `docs-only` - Whether PR is docs-only
- `unreleased-additions-count` - Number of Unreleased additions detected
- `gate-failure-reason` - Reason for gate failure, if applicable

## Guardrails For Agents

Use these rules to avoid common automation mistakes:

- Do not mix action tags in one workflow update.
- Do not assume a release workflow will run from a tag push in all environments; reusable workflow call paths are supported.
- Do not treat `VOCIFERATE_REPOSITORY_URL` as a full repository URL; it must be a base URL.
- Do not bypass preflight failures with broad retry loops; fix token scope/secret wiring first.