Operating The Frank Papers — Research, Dossiers, and Publishing

Last updated 2026-07-15 ·faa3f99

This is the operational companion to Building The Frank Papers. That post explains why there’s a third series and what the dossier gate is for. This one is the cookbook: scaffold, dossier, prose, cover, ship.

    graph TD
    subgraph repo["Repository"]
        scaffold["blog/content/docs/papers/NN-slug/index.md"]
        dossier["docs/papers-dossiers/NN-slug/dossier.md"]
        cover["blog/static/images/papers/NN-*.png"]
    end

    subgraph gate["Dossier Gate"]
        validate["scripts/validate-dossier.py"]
        sections["§1–§6 skeleton<br/>frontmatter checks"]
        bib["§8 bibliography<br/>references correct"]
    end

    subgraph publish["Publish"]
        hugo["hugo build<br/>0 errors"]
        shortcodes["papers/ shortcodes<br/>6 available"]
        commit["commit + push<br/>(CI rebuilds blog)"]
    end

    scaffold --> validate
    dossier --> validate
    validate -->|"passes"| shortcodes
    shortcodes --> hugo
    cover --> hugo
    hugo --> commit
  

What Ready to Write Looks Like

• blog/content/docs/papers/NN-slug/index.md exists with series: papers frontmatter and the §1–§6 skeleton.
• docs/papers-dossiers/NN-slug/dossier.md exists.
• python scripts/validate-dossier.py docs/papers-dossiers/NN-slug/dossier.md exits 0.

Steps

Scaffold a New Paper

# Create the paper bundle
hugo new content/docs/papers/NN-slug/index.md

# Create the dossier directory
mkdir -p docs/papers-dossiers/NN-slug/
touch docs/papers-dossiers/NN-slug/dossier.md

Write and Validate the Dossier

The dossier.md has sections: Problem Statement, Existing Solutions, Vendors Considered, Selection Criteria, Selected Approach, Open Questions.

python scripts/validate-dossier.py docs/papers-dossiers/NN-slug/dossier.md

The gate checks that every required section is present and above a minimum length. It exits non-zero if anything is missing — the PR check enforces this before review.

Use the Paper Shortcodes

Generate a Cover Image

The cover image lives at blog/static/images/papers/NN-descriptive-slug.png. Each Paper gets a unique AI-generated cover from a prompt composed by the blog-craft metaphor system. The prompt encodes the Paper’s central metaphor into Stable Diffusion syntax.

# The cover is generated as part of the blog-craft pipeline.
# See the building post for the prompt composition method.

Publish

hugo   # Must exit 0
git add blog/content/docs/papers/NN-slug/ \
        docs/papers-dossiers/NN-slug/ \
        blog/static/images/papers/NN-*.png
git commit -m "feat(papers): Paper NN — Title"

Recover

Dossier Validation Fails

python scripts/validate-dossier.py docs/papers-dossiers/NN-slug/dossier.md --verbose

Common failures:

• Section below minimum word count — expand the analysis.
• Missing required section — add the section header and content.
• References don’t match [@key] usage in prose — check §6 and §8 are in sync.

Cover Image Not Appearing

# Check the file exists at the expected path
ls -la blog/static/images/papers/NN-*.png

# Check the frontmatter reference
grep cover blog/content/docs/papers/NN-slug/index.md

Weight Collision with Another Paper

# Check weights across all papers
grep -h "weight:" blog/content/docs/papers/*/index.md | sort -t: -k2 -n

Weights should be unique. If two papers share a weight, the sidebar ordering is undefined. faa3f993 was a dedicated fix for weight sorting bugs.

Missteps

References

• Building Post — The Frank Papers
• Paper Bibliography Reference
• scripts/validate-dossier.py