Agent Authoring Contract

Agent Authoring Contract

This file describes the preferred authoring path for agents editing sites that use the shared Quantalumin generator.

Core Rule

Agents should prefer the highest-level shared authoring primitive that preserves markdown as the source of truth.

Use this order:

1. plain markdown for ordinary prose and headings
2. fenced structured blocks for repeated brochure-style content
3. shortcodes for true widgets, citations, utilities, or embeds
4. raw HTML only when no shared markdown/block/shortcode path exists

Prefer Plain Markdown For

• headings
• paragraphs
• ordinary links
• ordinary lists
• normal images and captions
• standard section attr blocks

Prefer Structured Fenced Blocks For

• people/team/committee cards
• gallery grids
• contact cards
• stats/metrics
• testimonials
• FAQs
• booking widgets and reservation pickers
• public calendars / what’s-on views
• funding discovery widgets / Fundalumin campaign lists
• buttons rows

See:

• structured-blocks.manifest.json

Prefer Shortcodes For

• widgets like quiz, skill-meter, pydoc
• citations and references
• true embeds
• icon and utility helpers

See:

• shortcodes.manifest.json

Media And Embed Rule

• Prefer markdown image syntax ![]() for images and iframe-backed embeds where the shared media pipeline already supports them.
• Prefer the shared embed shortcode only when authored parameters like height, aspect, sandbox, or allow are needed explicitly.
• Do not switch to raw HTML iframe markup in content unless the shared markdown and shortcode paths cannot express the requirement.

Styling Rule

Agents should prefer shared scoped tokens over one-off CSS or site-local template changes.

Preferred scope order:

1. site
2. page_type
3. page
4. section
5. block

Prefer the surface token group first, then color, width, space, type, radius, and shadow.

See:

• editor-surface.manifest.json

Section Rule

Treat banner, spotlight, and wrapper as legacy presets, not the primary conceptual model.

When reasoning about changes, think in:

• flow
• width
• spacing
• padding
• density
• alignment
• surface

Anti-Patterns

Agents should avoid:

• raw HTML for repeated content structures already covered by blocks
• per-site layouts/ forks
• per-site theme copies or symlinks
• site-specific head/runtime chains
• editing built output as source
• HTML-as-source workflows for editor round-tripping
• using include or purchasemembership as a default content authoring path without a clear need

MCP-Oriented Catalogs

The intended MCP-facing generator catalogs are:

• generator-system-map.md
• shortcodes.manifest.json
• structured-blocks.manifest.json
• editor-surface.manifest.json

Future bridge/API work should expose these catalogs directly rather than asking agents to infer capabilities by scraping templates.