QuantaLumin Website Agent Guide

This is the canonical guide for agents editing QuantaLumin website workspaces. Workspace-local AGENTS.md files should point here and add only site-specific exceptions.

Core Rules

• Markdown content is the source of truth.
• Hugo rendering is owned by the shared quantalumin/generator theme.
• Do not edit generated output such as public/, resources/, or published server directories as source.
• Do not create per-site layouts/ forks, copied generator themes, or local runtime asset chains.
• Shared rendering, CSS, JavaScript, editor, PDF, shortcode, and partial changes belong in quantalumin/generator.

Authoring Order

Use the highest-level shared primitive that preserves Markdown source:

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

Website Workflows

• Prefer editing content in the managed workspace and committing back to Forgejo.
• Use draft/preview hosts for interactive review before production publish.
• Keep site-specific configuration in front matter or Hugo config.
• Keep secrets, live tokens, and environment-specific service URLs out of website repos unless the generator docs explicitly define that field as safe.

Styling And Layout

• Prefer generator-supported params, section attrs, structured blocks, scoped tokens, and shared style contracts over site-local CSS.
• Treat banner, spotlight, and wrapper as compatibility presets; reason about flow, width, alignment, surface, spacing, media placement, and density.
• If a visual change should apply to more than one site, implement it in the generator and validate it with the visual regression workflow.

References Agents Should Read

• Generator docs: https://generator.quantalumin.com/
• Mental model: https://generator.quantalumin.com/docs/hugo/mental-model/
• Agent authoring contract: https://generator.quantalumin.com/docs/editor/agent-authoring-contract/
• Shortcode reference: https://generator.quantalumin.com/docs/reference/shortcodes-manifest/
• Structured blocks: https://generator.quantalumin.com/docs/reference/structured-blocks-manifest/
• Editor surface contract: https://generator.quantalumin.com/docs/reference/editor-surface-manifest/

Recommended Workspace Stub

Use this as the default root AGENTS.md for QuantaLumin website workspaces:

# AGENTS.md

This is a QuantaLumin website workspace.

Follow the canonical website agent guide:
https://generator.quantalumin.com/docs/agents/

Site-specific notes:
- Content lives in Markdown.
- Do not edit generated output.
- Shared theme, runtime, editor, PDF, shortcode, and partial changes belong in
  quantalumin/generator.