docs that maintainthemselves

Maintain documentation from source changes

Holocron Maintain watches every documentation page that includes a prompt field in its frontmatter. The prompt records how the page was generated and identifies its source files, folders, and URLs.

bash

1npx -y "@holocron.so/cli" maintain --since origin/main

When a referenced source changes, Maintain gives the current page, its generation prompt, and the relevant source changes to OpenCode. The page remains unchanged when the source change does not affect its content.

Ask AI about this page

Generate a maintainable page

The page-level prompt is the original instruction used to generate the page. Use @/path for files and folders from the repository root. Use @./path or @../path when the source sits next to the MDX page. Prefix remote sources with @https://. Bare URLs in prose are not references.

mdx

12345678910111213141516---
$schema: https://holocron.so/frontmatter.json
title: Authenticate API requests
sidebarTitle: Authentication
description: Authenticate requests with sessions, API keys, and GitHub Actions OIDC.
prompt: |
  Write the authentication guide from @/src/auth/ and
  @/src/middleware/session.ts.
  Use @https://github.com/example/project/releases for recent behavior changes.
  Explain sessions, API keys, and GitHub Actions OIDC authentication.
  Include a complete TypeScript example for every method.
---

# Authentication

Use a session or API key to authenticate API requests.

diagram

  repository root
       │
       ├── src/auth/                         ◄── @/src/auth/
       ├── src/middleware/session.ts         ◄── @/src/middleware/session.ts
       └── website/src/pages/docs/auth.mdx
                   │
                   └── @./setup.mdx            relative to this page

@/ always starts at the git repository root, so the path stays valid if you move the MDX file. @./ and @../ start at the MDX file. @https:// marks a remote source. A file reference selects the page when that file changes. A folder reference selects it when any tracked file inside the folder changes. GitHub release events and explicit routine runs can select matching @https:// URL references.

The Holocron skill adds this field by default when an AI coding agent creates a new MDX page. It records the real sources used to produce the page, so future agents can reproduce and update the content instead of guessing its intent. See skill discovery for agent setup.

Review changed sources

Pass a Git reference when running locally or in another CI system. Holocron compares its merge base with HEAD, selects affected pages, and starts one OpenCode session.

bash

1npx -y "@holocron.so/cli" maintain --since origin/main

Use --dry-run to inspect the selection without authentication or model usage.

bash

1npx -y "@holocron.so/cli" maintain --since origin/main --dry-run

Run a routine review

Use --all with a run prompt for work that is not tied to one changed source, such as grammar, SEO, links, or style checks.

bash

12npx -y "@holocron.so/cli" maintain --all \
  --prompt "Audit every page for weak titles and descriptions."

Long instructions can live in a versioned Markdown file.

bash

12npx -y "@holocron.so/cli" maintain --all \
  --prompt-file .holocron/prompts/weekly-review.md

The run prompt is temporary. It does not replace page generation prompts.

OpenCode execution

Maintain uses one OpenCode session for the complete run. The main agent groups independent pages by source, delegates those groups as parallel tasks, and validates every changed MDX file before publication.

If no page needs an update, the command exits successfully without creating a branch or pull request.

Authentication and billing

Maintain is a Holocron Pro feature when using Holocron-hosted models. GitHub Actions authenticates through OIDC with id-token: write, so the workflow does not need a stored Holocron key.

Other CI systems can set HOLOCRON_KEY. Local runs use the existing holocron login session. Pass --project only when the local account has multiple projects.

Options

Option	Purpose
`--all`	Review all prompted pages, or every page when used with a run prompt.
`--since <ref>`	Detect source changes between the ref merge base and `HEAD`.
`--prompt <text>`	Add temporary instructions for this run.
`--prompt-file <path>`	Read temporary instructions from a Markdown file.
`--dry-run`	Report selected pages without a model call.
`--pull-request`	Update the current PR or open one PR for this run.
`--project <id>`	Select a project for a local session with multiple projects.

See GitHub Actions for push, pull request, and scheduled workflows.