---
name: fab-academy-documentation-publisher
description: Build, verify, convert, and publish Fab Academy documentation from Notion exports, project folders, session notes, media files, and MkDocs sites. Use when the user asks to write or update Fab Academy week/final-project documentation, verify Notion documentation against local code or design files, convert Notion exports into site pages, compress/rename media for browser delivery, run mkdocs build checks, or commit and push Fab Academy site updates.
---

# Fab Academy Documentation Publisher

## Purpose

Turn raw Fab Academy work into accurate publishable documentation. Optimize for factual consistency with the actual repository, clean media handling, readable student voice, and a passing strict site build.

## Intake

Before editing, identify the target week or project and the canonical destination:

- Local source project folder: code, CAD, firmware, images, videos, design files.
- Current documentation source: Notion page, Notion export zip, existing Markdown page, transcript, or user notes.
- Published site repo, usually `youssef-kusibati`, and the expected Markdown path under `docs/`.
- Required output: factual review, Notion edit, Markdown page, media cleanup, local preview, commit/push, or all of these.

If the user says "as usual" or refers to prior instructions, infer the usual standards from the existing site before asking. Read nearby week pages and `mkdocs.yml` first.

## Workflow

1. Inspect the site structure.
   - Read `mkdocs.yml`, nearby `docs/weekly_review/week_*.md`, shared CSS/JS, and the target page if it exists.
   - Preserve naming conventions, nav structure, heading style, relative paths, and existing prose tone.

2. Verify facts from source artifacts.
   - Check the relevant code, firmware, CAD scripts, board files, screenshots, videos, transcripts, and Notion text.
   - Do not repeat claims that are only aspirational. Separate "what worked", "what failed", "how it was fixed", and "what remains".
   - When documenting electronics or firmware, prefer exact board names, pins, addresses, protocols, serial ports, and test outcomes from the repo or logs.

3. Convert or rewrite documentation.
   - For Notion exports, extract useful text and assets, then rewrite into the existing Markdown style rather than dumping exported markup.
   - Rename assets to short descriptive lowercase names.
   - Put files in the existing week-specific media/design folder pattern.
   - Replace absolute local paths with relative site paths.
   - Keep the user's first-person learning voice, but clean typos and unclear phrasing.

4. Handle media for the web.
   - Compress videos above the site target size, usually under 5 MB when the user references that constraint.
   - Use this ffmpeg command by default for video compression:
     `ffmpeg -i input_video -vcodec libx264 -crf 25 -preset medium -vf scale=-2:1080 -acodec libmp3lame -q:a 4 -ar 48000 -ac 2 output_video.mp4`
   - Keep the original if it is important, but link the compressed version in published pages.
   - Check image dimensions and file sizes; compress large images without destroying evidence value.

5. Build and inspect.
   - Run the repo's existing build command; for MkDocs sites, use `mkdocs build --strict` when available.
   - Fix broken links, bad embeds, missing nav entries, malformed Markdown, and media references.
   - For significant layout/media changes, run a local preview when practical and inspect the affected page.

6. Publish only when requested or clearly implied.
   - Check `git status` and avoid unrelated changes.
   - Commit with a direct message and no AI co-author footer.
   - Push to the expected remote/branch only after the build passes or after clearly reporting why it cannot.

## Quality Bar

- The page should document the real process, not just the final success.
- Every important claim should be traceable to a local artifact, Notion source, transcript, or user-provided file.
- Videos and images should load in a normal browser without relying on local-only paths.
- The final response should include the build result, published files or Notion page touched, and any remaining manual checks.

## Common Traps

- Do not claim a circuit, interface, or machine worked unless the session evidence or source files show.
- Do not leave raw Notion export filenames or long hash-like media names in final Markdown.
- Do not embed videos as images; use the site's established video/embed pattern.
- Do not overwrite unrelated week pages while doing a broad search-and-replace.
- Do not push if the user only asked for a review or factual accuracy check.