docs: sync make-pdf image-policy docs with final shipped behavior (v1.58.0.0)

The docs wave (87594420) predated the final review-wave commits, so two
docs drifted from shipped behavior:

- make-pdf/SKILL.md.tmpl + generated SKILL.md: remote images are BLOCKED
  with a visible placeholder (not warned-and-kept); out-of-tree reads
  (including via symlink) warn and --strict makes them fatal; --strict
  also covers oversized (>64MB) and non-regular files; troubleshooting
  entry now names the actual "[remote image blocked]" symptom.
- docs/howto-diagrams-and-formats.md: same corrections in the image
  section, CI section, and troubleshooting.
- README.md: docs/howto-diagrams-and-formats.md added to the Docs table
  (was unreachable from any entry-point doc).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -431,6 +431,7 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid
 | Doc | What it covers |
 |-----|---------------|
 | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
+| [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets |
 | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge |
 | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` |
 | [GBrain Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting |

docs/howto-diagrams-and-formats.md

@@ -49,6 +49,12 @@ markdown file) and **never truncate** — every image caps at the content box.
 Oversized photos downscale to print resolution (300dpi at the content width),
 so a phone photo doesn't bloat the document.
 
+Image safety defaults: remote (http/https) images are **blocked with a
+visible placeholder** unless you pass `--allow-network`. An image path that
+resolves outside the markdown's directory (even through a symlink) still
+inlines but warns loudly. Files over 64MB and non-regular files (fifos,
+devices) degrade to a placeholder instead of hanging the render.
+
 Per-image directives go immediately after the image:
 
 ```markdown
@@ -113,8 +119,10 @@ For documents, embed the `.mmd` source in your markdown instead of the PNG —
 make-pdf generate docs.md --strict
 ```
 
-Missing local images and unfetched remote images exit non-zero instead of
+Missing local images, blocked remote images, out-of-tree image reads (a path
-rendering a placeholder — for docs pipelines where a broken image should
+or symlink resolving outside the markdown's directory), oversized files
+(>64MB), and non-regular files all exit non-zero instead of degrading to a
+warning or placeholder — for docs pipelines where a broken image should
 break the build.
 
 ## Troubleshooting
@@ -127,5 +135,7 @@ break the build.
   trick — top-level `flowchart TB`, two subgraphs with `direction LR` and
   `direction RL`, connect the *subgraphs* (node-level edges across subgraph
   boundaries silently disable `direction`).
-- **Remote images** → not fetched by default (offline posture). Pass
+- **"[remote image blocked]" placeholder** → remote images are never fetched
+  by default (offline posture); the tag is replaced with a visible
+  placeholder so Chromium can't fetch it at print time either. Pass
   `--allow-network` to opt in.

make-pdf/SKILL.md

@@ -625,6 +625,13 @@ markdown file). Every image caps at the content box — zero truncation, ever.
 Oversized photos downscale to print resolution (300dpi) so payloads stay
 small with no visible quality loss.
 
+Remote (http/https) images are **blocked with a visible placeholder** by
+default — offline posture; pass `--allow-network` to fetch them. An image
+that resolves outside the markdown's directory (even via symlink) still
+inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or
+non-regular files (fifos, devices) degrade to a placeholder instead of
+hanging the run.
+
 Per-image directives, written immediately after the image:
 
 ```
@@ -657,7 +664,8 @@ $P generate readme.md out.docx --to docx    # Word: content fidelity (headings,
 ### CI mode — fail loud on missing assets
 
 ```bash
-$P generate docs.md --strict     # missing/remote images exit non-zero
+$P generate docs.md --strict     # missing, remote, out-of-tree, oversized,
+                                 # and non-regular-file images exit non-zero
                                  # instead of warn + placeholder
 ```
 
@@ -682,7 +690,8 @@ Branding:
 Output:
   --to pdf|html|docx         Output format (default: pdf). html = single
                              self-contained file; docx = content fidelity.
-  --strict                   Missing/remote images fail the run (CI mode).
+  --strict                   Missing, remote, out-of-tree, oversized, or
+                             non-regular-file images fail the run (CI mode).
   --page-numbers             "N of M" footer (default on)
   --tagged                   Accessible PDF (default on)
   --outline                  PDF bookmarks from headings (default on)
@@ -690,8 +699,9 @@ Output:
   --verbose                  Per-stage timings
 
 Network:
-  --allow-network            Fetch external images. Off by default
+  --allow-network            Fetch external images. Off by default: remote
-                             (blocks tracking pixels).
+                             images render as a visible blocked placeholder
+                             (no tracking pixels fetch at print time).
 
 Metadata:
   --title "..."              Document title (defaults to first H1)
@@ -719,8 +729,9 @@ If the user has a `.md` file open and says "make it look nice", propose
   `--no-syntax` once that flag exists. For now, remove fenced code blocks
   and regenerate.
 - Paged.js timeout → probably no headings in the markdown. Drop `--toc`.
-- External image missing → add `--allow-network` (understand you're giving
+- "[remote image blocked]" placeholder in the output → add `--allow-network`
-  the markdown file permission to fetch from its image URLs).
+  (understand you're giving the markdown file permission to fetch from its
+  image URLs).
 - Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`.
 
 ## Output contract

make-pdf/SKILL.md.tmpl

@@ -121,6 +121,13 @@ markdown file). Every image caps at the content box — zero truncation, ever.
 Oversized photos downscale to print resolution (300dpi) so payloads stay
 small with no visible quality loss.
 
+Remote (http/https) images are **blocked with a visible placeholder** by
+default — offline posture; pass `--allow-network` to fetch them. An image
+that resolves outside the markdown's directory (even via symlink) still
+inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or
+non-regular files (fifos, devices) degrade to a placeholder instead of
+hanging the run.
+
 Per-image directives, written immediately after the image:
 
 ```
@@ -153,7 +160,8 @@ $P generate readme.md out.docx --to docx    # Word: content fidelity (headings,
 ### CI mode — fail loud on missing assets
 
 ```bash
-$P generate docs.md --strict     # missing/remote images exit non-zero
+$P generate docs.md --strict     # missing, remote, out-of-tree, oversized,
+                                 # and non-regular-file images exit non-zero
                                  # instead of warn + placeholder
 ```
 
@@ -178,7 +186,8 @@ Branding:
 Output:
   --to pdf|html|docx         Output format (default: pdf). html = single
                              self-contained file; docx = content fidelity.
-  --strict                   Missing/remote images fail the run (CI mode).
+  --strict                   Missing, remote, out-of-tree, oversized, or
+                             non-regular-file images fail the run (CI mode).
   --page-numbers             "N of M" footer (default on)
   --tagged                   Accessible PDF (default on)
   --outline                  PDF bookmarks from headings (default on)
@@ -186,8 +195,9 @@ Output:
   --verbose                  Per-stage timings
 
 Network:
-  --allow-network            Fetch external images. Off by default
+  --allow-network            Fetch external images. Off by default: remote
-                             (blocks tracking pixels).
+                             images render as a visible blocked placeholder
+                             (no tracking pixels fetch at print time).
 
 Metadata:
   --title "..."              Document title (defaults to first H1)
@@ -215,8 +225,9 @@ If the user has a `.md` file open and says "make it look nice", propose
   `--no-syntax` once that flag exists. For now, remove fenced code blocks
   and regenerate.
 - Paged.js timeout → probably no headings in the markdown. Drop `--toc`.
-- External image missing → add `--allow-network` (understand you're giving
+- "[remote image blocked]" placeholder in the output → add `--allow-network`
-  the markdown file permission to fetch from its image URLs).
+  (understand you're giving the markdown file permission to fetch from its
+  image URLs).
 - Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`.
 
 ## Output contract