docs(checkmate): add interval-unit incident runbook

[obrera]

Summary

Adds an operational incident note to the Checkmate skill page covering interval-unit mismatch behavior and safe recovery steps.

Changes

• Document critical gotcha: monitor interval in DB/runtime must be milliseconds (60000 for 60s).
• Describe symptom when value is 60 (near-1s checks, high churn).
• Add quick detection workflow (docker stats, interval distribution query, cadence validation).
• Add safe remediation playbook (backup, normalize, restart, verify cadence).
• Add optional hardening recommendations (retention/TTL, resource limits, reduce expensive monitor frequencies).

Validation

• npm run build

[gemini-code-assist]

Summary of Changes

Hello @obrera, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily enhances the Checkmate skill documentation by adding a critical operational incident runbook. This new section addresses a common interval unit mismatch issue, providing clear detection methods, a safe remediation playbook, and optional hardening recommendations. Additionally, the pull request introduces a build stamp integration across the project, embedding commit information into the site's build artifacts for improved version tracking.

Highlights

• Checkmate Documentation Enhancement: Added a comprehensive operational incident note to the Checkmate skill page, detailing the critical issue of monitor interval units being treated as milliseconds instead of seconds.
• Incident Detection and Remediation: Included clear steps for quickly detecting interval unit mismatches, a safe playbook for remediation (including data backup, interval normalization, and verification), and optional hardening recommendations.
• Build Stamp Integration: Implemented a new Astro integration to embed the commit SHA and build date into the site's metadata and a version.json file for improved build traceability and version tracking.

Changelog

• Dockerfile
  • Updated the build process to accept and pass a COMMIT_SHA argument to the bun run build command.
• astro.config.mjs
  • Modified the Astro configuration to import and utilize a new buildStamp integration.
  • Set an x-commit meta tag in the HTML head using the commit SHA.
  • Integrated the buildStamp with commit details and repository information.
• src/content/docs/skills/checkmate.md
  • Expanded the Checkmate documentation with a new section titled "Operational gotcha: monitor interval units."
  • Added detailed instructions for detecting interval unit mismatches, including docker stats and MongoDB aggregation queries.
  • Provided a safe remediation playbook with steps for backing up data, normalizing intervals, and restarting the server.
  • Included optional hardening recommendations for retention policies, resource limits, and frequency reduction.
• src/integrations/build-stamp.ts
  • Added a new TypeScript file defining an Astro integration named build-stamp.
  • Implemented functionality to generate a version.json file containing the commit SHA, a GitHub URL to the commit, and the build timestamp during the build process.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/docker.yml

Activity

• No specific activity (comments, reviews, progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces a new Astro integration to embed build information (commit SHA, repository URL, and build timestamp) into a version.json file and an x-commit meta tag. It also adds crucial documentation regarding a "monitor interval units" operational gotcha in Checkmate, providing detection and remediation steps. The changes enhance traceability and provide valuable operational guidance.

[obrera]

Addressed Gemini feedback in src/integrations/build-stamp.ts: built now uses process.env.BUILD_TIMESTAMP || new Date().toISOString() for reproducible builds when BUILD_TIMESTAMP is provided.

[obrera]

@gemini-code-assist please review

[gemini-code-assist]

Code Review

This pull request adds an important operational runbook for a critical interval-unit mismatch issue in Checkmate, which is a valuable addition. It also introduces a build stamping mechanism to embed the commit SHA into the documentation site. My review includes two main points: one suggestion to improve the maintainability of the new build stamp integration by avoiding a hardcoded repository name, and a more critical point about an inconsistency in the documentation that the new changes introduce. The current documentation example for creating a monitor will lead users directly into the problem that this PR is trying to warn them about.

[obrera]

@gemini-code-assist please review

[gemini-code-assist]

Code Review

This pull request adds a valuable operational runbook to the Checkmate skill documentation, addressing a critical issue with monitor interval units. The provided steps for detection and remediation are clear and well-documented. The change to support reproducible build timestamps is also a good enhancement. I have one suggestion to improve the backup command in the new documentation.

[obrera]

@gemini-code-assist please review

[gemini-code-assist]

Code Review

The pull request effectively addresses a critical operational 'gotcha' regarding monitor interval units in Checkmate by updating documentation and providing clear remediation steps. The addition of BUILD_TIMESTAMP environment variable for build stamping is a good improvement for build reproducibility. The changes are well-documented and provide valuable information for users.