Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Run documentation maintenance in GitHub Actions

This is the GitHub Actions path. Maintain reads the push event, updates matching MDX pages, and opens a pull request. For a parent agent that should open the PR itself, use the parent-agent flow.
GitHub Actions provides the Git range, repository identity, OIDC authentication, and GitHub token. No stored Holocron key is needed.
On a GitHub Actions run, Maintain adds publish instructions to the session prompt. OpenCode updates the selected MDX pages, then opens a pull request when those files changed. Local and parent-agent runs do not get those instructions, so they never create a branch or pull request.
  push to main
        │
        v
  holocron maintain
        │
        v
  OpenCode updates MDX pages
        │
        ├── no MDX changes ──> stop
        └── MDX files changed
                │
                v
         branch holocron/maintain-<timestamp>
                │
                v
         gh pr create into main
Keep GITHUB_TOKEN on the Maintain step so OpenCode can push the new branch and open the pull request. Leave checkout credentials enabled. Do not set persist-credentials: false.

After every main-branch push

Run holocron maintain with no args. GitHub writes the push payload to GITHUB_EVENT_PATH. Maintain reads before (the branch tip before this push) and after (the new tip, this checkout), then runs git diff before..after.
That range is the whole push. Five commits in one push all count. It is not HEAD~1.
  git push (one or more commits)
           │
           v
  GITHUB_EVENT_PATH
    before  = old tip of the branch
    after   = new tip
           │
           v
  git diff before..after
           │
           v
  pages whose @/ sources sit in that diff
Checkout needs fetch-depth: 0 so those SHAs exist locally. A new-branch push has before all zeros. Maintain then uses git diff-tree --root on after.
If MDX files change, OpenCode creates holocron/maintain-<timestamp> and opens one pull request into main. It never commits on main or on any other existing branch.
name: Maintain documentation

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - run: npx -y "@holocron.so/cli" maintain
        env:
          GITHUB_TOKEN: ${{ github.token }}
contents: write lets OpenCode create the maintain branch. pull-requests: write lets it open the pull request. id-token: write authenticates Holocron over OIDC.
Protect main with a ruleset that requires a pull request and does not let GitHub Actions bypass it. The token can still create holocron/maintain-* branches.
GitHub blocks pull requests from Actions until you enable Allow GitHub Actions to create and approve pull requests in Settings, Actions, General, Workflow permissions. See the GitHub docs.

Scheduled maintenance

Use a schedule for routine audits that do not depend on a specific source change.
name: Weekly documentation review

on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - run: |
          npx -y "@holocron.so/cli" maintain \
            --all \
            --prompt-file .holocron/prompts/weekly-review.md
        env:
          GITHUB_TOKEN: ${{ github.token }}

Do not cancel active runs

Do not set cancel-in-progress: true for push maintenance. A later push compares only its own before and after states, so cancelling the preceding run can leave its source changes unreviewed.
A run that changes no MDX files creates no branch and no pull request.

Use your own model

The workflows above use the Holocron-hosted model and bill the project's Pro subscription. OIDC is enough. No provider API key.
To run Anthropic, OpenAI, or any other OpenCode provider, pass --model provider/model and set that provider's env var. Holocron auth is not used. See the OpenCode providers page for the supported keys.
Use a dedicated provider key. The OpenCode session can run git and gh, and it can read the environment.
- run: npx -y "@holocron.so/cli" maintain --model anthropic/claude-sonnet-4-5
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    GITHUB_TOKEN: ${{ github.token }}
You can drop id-token: write when the Holocron-hosted model is not used. Keep contents: write and pull-requests: write so OpenCode can still open the pull request.