From d5a92fead817ca7b4a1db5bc70415490109ffc5e Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Wed, 11 Mar 2026 18:11:34 -0700 Subject: [PATCH] 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 --- docs/how-to/jobsync/build-jobsync-container.md | 5 +++-- docs/how-to/knowledgebase/review-documentation.md | 6 +----- mise-tasks/docs-preview | 2 +- mise-tasks/docs-review | 6 ++---- 4 files changed, 7 insertions(+), 12 deletions(-) mode change 100644 => 100755 mise-tasks/docs-preview diff --git a/docs/how-to/jobsync/build-jobsync-container.md b/docs/how-to/jobsync/build-jobsync-container.md index de75915..d9653e9 100644 --- a/docs/how-to/jobsync/build-jobsync-container.md +++ b/docs/how-to/jobsync/build-jobsync-container.md @@ -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 diff --git a/docs/how-to/knowledgebase/review-documentation.md b/docs/how-to/knowledgebase/review-documentation.md index fe17449..1dfba4e 100644 --- a/docs/how-to/knowledgebase/review-documentation.md +++ b/docs/how-to/knowledgebase/review-documentation.md @@ -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 diff --git a/mise-tasks/docs-preview b/mise-tasks/docs-preview old mode 100644 new mode 100755 index a968797..38c14c3 --- a/mise-tasks/docs-preview +++ b/mise-tasks/docs-preview @@ -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( diff --git a/mise-tasks/docs-review b/mise-tasks/docs-review index e7c7aa2..d2aee76 100755 --- a/mise-tasks/docs-review +++ b/mise-tasks/docs-review @@ -156,14 +156,12 @@ def main( "• If ArgoCD app: is it synced? (argocd app get )\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 [/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 [/cyan] for a rendered visual check", title="[bold yellow]Review Guidance[/bold yellow]", border_style="yellow", ))