[inureyes]

Summary

make webpage-build deleted webpage/site/public/{en,ko}/manual and then failed opaquely inside zensical against a nonexistent docs_dir, because it ran the same unmet MkDocs dependency the thirteen docs-* targets already guard, but it was not itself a docs-* target and stayed out of that earlier pass. This adds docs-guard to webpage-build so it fails fast with the same explanation instead, and makes a deliberate, documented choice for webpage-deploy rather than leaving that question open.

What changed

• Makefile: webpage-build now declares docs-guard as a prerequisite and its ## help string carries the same (manual sources not in this checkout) suffix as the other guarded targets, so make help states the dependency up front.
• Makefile: webpage-deploy is intentionally left off docs-guard, since scripts/deploy_webpage.sh never touches zensical or docs_dir and cannot fail the way webpage-build does, and docs-guard checks docs/en (a build input) rather than the manual output the script actually reads. It now warns, without blocking, when webpage/site/public/en/manual or .../ko/manual is missing, and a comment above the target records the reasoning.

Test plan

• On a checkout without docs/en: make webpage-build fails at docs-guard before the rm -rf runs, and webpage/site/public/{en,ko}/manual stay absent before and after (ls checked both times).
• make help shows the new (manual sources not in this checkout) suffix on webpage-build.
• Overriding DOCS_MANUAL_DIR to an existing directory lets the guard pass through unchanged into the rm -rf and uv run zensical steps (fails only on the unrelated absence of zensical in this environment, confirming the guard itself is a presence check, not a hard refusal).
• make -n webpage-deploy confirms the new warning block is syntactically valid Make/shell, and the warning condition was exercised in isolation against the current manual-less checkout.

Closes #1138

[inureyes]

Implementation Review Summary

Intent

Add the existing docs-guard prerequisite to webpage-build so it fails fast on a checkout without the MkDocs manual sources instead of deleting webpage/site/public/{en,ko}/manual and then failing opaquely inside zensical, and settle the open question about webpage-deploy deliberately rather than leaving it unaddressed.

Findings Addressed

None. No CRITICAL or HIGH findings were found, and no MEDIUM findings warranted a change. Nothing was committed.

Remaining Items

• Warnings print to stdout rather than stderr (LOW). This is consistent with docs-guard and every other echo in this Makefile, so changing it here alone would be the inconsistency. No action recommended.
• webpage/site/public/{en,ko}/manual is spelled literally in the new check rather than factored into a variable (LOW). The pre-existing rm -rf line in webpage-build already spells both paths literally, so the new code matches the local convention. Extracting a variable would widen the diff past the issue's scope.

Verification

• All stated requirements implemented. All five acceptance criteria in chore(build): guard webpage-build against the missing MkDocs manual sources #1138 verified independently against the working tree, not just read from the diff.
• AC1: webpage-build: docs-guard ## ... at Makefile:942, prerequisite placed before the ## marker exactly as docs-install:1003 and the other twelve guarded targets do.
• AC2: make webpage-build in this checkout (no docs/en) stops at docs-guard with the published-manual message. Confirmed live: the target's own Building documentation for webpage... echo never fires, rm -rf never runs, uv is never invoked, and webpage/site/public still holds only brands/ afterwards.
• AC3: the guard stays a presence check. make -n webpage-build DOCS_MANUAL_DIR=webpage passes straight through into the unchanged rm -rf, two uv run zensical build and pnpm build steps.
• AC4: make help parses the new line and renders webpage-build Build download webpage (static export) (manual sources not in this checkout) under Webpage Targets. The suffix is byte-identical to the thirteen pre-existing ones (twelve declared target: docs-guard ##, plus docs-pdf which carries extra prerequisites).
• AC5: scripts/deploy_webpage.sh was read end to end and the comment's claims hold. It runs pnpm install && pnpm run build in webpage/site, then commits and force-pushes out/ to the gh-pages branch of mlxcel-releases. It never mentions zensical, mkdocs.yml or docs_dir, so gating it on docs-guard (a docs/en presence check) would test the wrong precondition. Warning on the actual precondition, the built manual output, without blocking is the right call and the reasoning is recorded above the target.
• No placeholder/mock code remaining. No TODO, stub, or debug output in the diff.
• Integrated into project code flow. docs-guard is a real .PHONY target at Makefile:984; Make resolves it fine despite being defined below the webpage section, confirmed by the live run.
• Project conventions followed. Recipe lines are tab-indented, \ continuations are correct, and $(YELLOW)/$(RESET) are the variables defined at Makefile:54 and :56.
• Existing modules reused where applicable. The change reuses docs-guard rather than writing a second presence check.
• No unintended structural changes. git diff origin/main...HEAD is one file, 14 insertions and 1 deletion, entirely within Makefile:941-967. The verify-* targets and every other section are untouched.
• Tests pass. No Rust code changed, so no test run applies. git diff --check is clean, scripts/ci/check_cross_repo_refs.py reports OK, and CI is green with the Rust jobs correctly skipped by path filtering.

Behavior checks run

• make webpage-build (fails at the guard, which is the intended behavior in this checkout).
• make -n webpage-build DOCS_MANUAL_DIR=webpage.
• make -n webpage-deploy (the warn block expands to valid /bin/sh).
• The warn block executed standalone against this manual-less checkout: it prints both lines and exits 0, so ./scripts/deploy_webpage.sh still runs unconditionally on the next recipe line.
• make help.