Review build-jobsync-container, refine docs-preview tooling

- Review build-jobsync-container.md: fix nonexistent `mirror-sync` task
  reference (Forgejo mirrors sync automatically), mark reviewed
- Remove bat hint from docs-review checklist (output not visible in
  agent sessions), keep docs-preview hint as user-facing step
- Simplify review-documentation.md visual preview section
- Fix Python 3.14 tarfile deprecation warning in docs-preview

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Erich Blume 2026-03-11 18:11:34 -07:00
commit d5a92fead8
4 changed files with 7 additions and 12 deletions

View file

@ -1,6 +1,7 @@
---
title: Build JobSync Container
modified: 2026-03-08
modified: 2026-03-11
last-reviewed: 2026-03-11
tags:
- how-to
- jobsync
@ -19,7 +20,7 @@ The derivation is at `containers/jobsync/default.nix`. It uses `buildNpmPackage`
## Upgrading JobSync
1. Update the forge mirror: `mise run mirror-sync jobsync`
1. Verify the forge mirror is current: check `https://forge.eblu.me/mirrors/jobsync` (mirrors sync automatically)
2. Update `version` in `default.nix` to match the new upstream tag
3. Clear `hash` in `fetchgit` (set to `""`), build, grab the correct hash from the error
4. Clear `npmDepsHash` (set to `""`), build again, grab the correct hash

View file

@ -94,11 +94,7 @@ If changes are pending, investigate whether docs or infrastructure is stale.
## Visual Preview
After reviewing and editing a card, visually verify the rendered output.
**Quick scan (agent):** Have the agent display the card with `bat` for a terminal-based visual check.
**Full rendered preview:** Build the entire Quartz docs site locally and open directly to the card:
After reviewing and editing a card, visually verify the rendered output. This step is for the human reviewer — build the full Quartz docs site locally and open directly to the card:
```bash
mise run docs-preview how-to/knowledgebase/review-documentation

2
mise-tasks/docs-preview Normal file → Executable file
View file

@ -89,7 +89,7 @@ def main(
console.print("[bold]Extracting docs...[/bold]")
with tarfile.open(tarball, "r:gz") as tf:
tf.extractall(docroot)
tf.extractall(docroot, filter="data")
console.print("[bold]Starting preview container...[/bold]")
subprocess.run(

View file

@ -156,14 +156,12 @@ def main(
"• If ArgoCD app: is it synced? (argocd app get <app>)\n"
"• If Ansible role: does it apply idempotently? (--check --diff)\n"
"• If Pulumi: is there drift? (pulumi preview)\n\n"
"[bold]Visual Preview:[/bold]\n\n"
"• Agent: use [cyan]bat[/cyan] to display the reviewed card for user visual scan\n"
"• For full rendered preview: [cyan]mise run docs-preview <card-path>[/cyan]\n\n"
"[bold]After Review:[/bold]\n\n"
"• Update the card's frontmatter: [cyan]last-reviewed: "
+ str(today)
+ "[/cyan]\n"
"• Commit the change (along with any fixes)",
"• Commit the change (along with any fixes)\n"
"• User: run [cyan]mise run docs-preview <card-path>[/cyan] for a rendered visual check",
title="[bold yellow]Review Guidance[/bold yellow]",
border_style="yellow",
))