Documentation Steward

The HAAM Documentation Steward compares repository changes with the public documentation and proposes updates when implementation and documentation no longer agree.

The agent now runs inside the HAAM Vercel project. GitHub remains the source of repository evidence, the destination for proposed changes, and the place where a human decides whether anything should be published.

Responsibility

The steward has one named responsibility:

Keep the public operating record aligned with the system it describes.

A secured Vercel Cron invokes the agent daily. The review covers a configurable lookback period, currently seven days, so a missed invocation does not automatically create a gap. A separate authenticated API route supports deliberate manual reviews.

Architecture

Vercel Cron or authenticated API request
                    ↓
        Vercel Documentation Steward
                    ↓
        GitHub repository evidence
        - compare commits
        - read documentation
        - read current activity record
                    ↓
        OpenAI structured review
        - decision
        - confidence
        - evidence
        - risks
        - complete MDX proposals
                    ↓
        local path and content validation
                    ↓
        GitHub proposal branch and pull request
                    ↓
                human review
                    ↓
        merge and normal Vercel deployment

Runtime files

lib/docs-steward-vercel.js
app/api/cron/documentation-steward/route.js
app/api/agents/documentation-steward/trigger/route.js
vercel.json
data/docs-steward-activity.json
output/docs-steward/latest.md
content/docs/

The previous GitHub Actions workflow and local Git-based agent script have been removed. This leaves one production implementation and avoids maintaining two different definitions of the same agent.

Scheduled review

vercel.json registers the following daily cron job:

{
  "path": "/api/cron/documentation-steward",
  "schedule": "17 5 * * *"
}

Vercel schedules use UTC. The endpoint requires the CRON_SECRET Bearer token that Vercel automatically includes when invoking a secured cron route.

The scheduled review:

1. resolves the current master commit;
2. finds commits inside the configured audit window;
3. compares the oldest relevant parent with the current head;
4. excludes the steward's own generated files;
5. reads the current Fumadocs corpus directly through the GitHub API;
6. requests a schema-constrained model decision;
7. creates a pull request only when a supported update remains after validation.

Manual review

An authenticated request can start the same Vercel runtime:

POST /api/agents/documentation-steward/trigger
Authorization: Bearer <DOCS_STEWARD_TRIGGER_SECRET>
Content-Type: application/json

Example body:

{
  "auditDays": 7
}

Advanced calls may supply explicit baseSha and headSha values. A GET request to the same endpoint returns configuration status when authorized, without revealing secret values.

Permission boundary

Evidence contract

Every proposal records:

• the repository range reviewed;
• the files examined;
• the documentation affected;
• the reason for each revision;
• exact source evidence;
• model confidence;
• risks requiring reviewer attention;
• the Vercel runtime and trigger that produced the review.

Weak evidence should produce no edit. The system prompt explicitly instructs the agent to prefer no_change rather than inventing a useful-looking revision.

Prompt-injection boundary

Repository content is treated as untrusted evidence. Instructions contained inside code, comments, diffs, or documentation are not agent instructions. Only the fixed server-side system prompt and runtime configuration define the steward's authority.

Idempotency

Before creating a proposal, the runtime checks existing open pull requests for the same reviewed head commit. This prevents a repeated cron invocation from opening another proposal for the same repository state.

The agent also compares proposed content with the existing file before writing. A model suggestion that produces no actual change does not create a branch or pull request.

Vercel configuration

The production Vercel project requires:

• OPENAI_API_KEY;
• HAAM_DOCS_GITHUB_TOKEN, or the existing HAAM_EDITORIAL_GITHUB_TOKEN as a fallback;
• CRON_SECRET with a random value of at least 16 characters;
• DOCS_STEWARD_TRIGGER_SECRET for manual API requests.

Optional variables:

• HAAM_DOCS_REPOSITORY, defaulting to krishaamer/haam-landing-page;
• HAAM_DOCS_BASE_BRANCH, defaulting to master;
• DOCS_STEWARD_MODEL, defaulting to gpt-5.4-mini;
• DOCS_STEWARD_AUDIT_DAYS, defaulting to 7.

The GitHub token needs repository Contents and Pull Requests write permissions. It does not need permission to merge pull requests.

Failure behaviour

The cron and manual endpoints return structured errors and write failures to Vercel runtime logs. If an error occurs after an agent branch is created, the runtime attempts to remove that branch.

No production documentation is changed unless a human merges the resulting pull request.

Public record

The agent's architecture, permission model, and published proposal metrics appear at HAAM Documentation Steward.

The activity JSON is updated inside proposal branches. This means the public operating record itself goes through the same human review as the documentation changes it describes. Reviews that correctly conclude no_change remain visible in Vercel logs rather than creating artificial repository activity.

Review standard

A human reviewer remains responsible for:

• factual accuracy;
• institutional and brand language;
• accessibility and legal commitments;
• historical claims;
• whether a proposed change belongs in the permanent public record.