# UpSolution — Content Agent Documentation

> Entry point for AI agents that generate WordPress page content (`post_content`) using UpSolution shortcodes and pre-built section templates. Optimized for shortcode names, valid parameter values, container nesting rules, and ready-to-paste section recipes for Impreza and Zephyr themes.
>
> Source plugin: us-core 8.45.2. Audience: content generation (no PHP/CSS knowledge required).

## Read in this order

1. [Composition rules](composition-rules.md): Cross-cutting rules for assembling valid `post_content` — root structure, nesting graph, attribute encoding (link picker, per-element CSS via `css="…"`, responsive single-value JSON), inline HTML allowlists per attribute, palette tokens, reusing pre-built sections, responsive overrides, and cross-shortcode anti-patterns. **Start here.**
2. [Shortcodes (73)](shortcodes.md): The full set of shortcodes available — containers, basic blocks, interactive blocks, and other building blocks. Each entry covers purpose, when to use, when to avoid, useful parameters with valid values, minimal copy-paste examples, and common combinations.
3. [Section templates (snapshot)](sections.md): Ready-made sections from the UpSolution library, grouped by category. The index lists each category; individual templates live in `content/sections/<category-id>.md` as self-contained shortcode blocks you can drop into `post_content` and edit. Use as starting points for full sections; tune per-template via the rules from (1).

## Common parameter groups

Three parameter packs are shared across most shortcodes and documented once each, instead of being repeated in every shortcode entry:

- [Effects](element-effects.md): scroll-driven motion (translate, opacity, blur, scale).
- [Display Logic](element-display-logic.md): conditional rendering (auth state, role, device, custom fields).
- [Design](element-design.md): per-element CSS, extra classes/ID, custom HTML attributes, visibility breakpoints.

## Cross-cutting reference

- [Dynamic Values](element-dynamic-values.md): the two subsystems that let one shortcode produce a different result per post / user / site — `{{…}}` text tokens (resolved by `us_replace_dynamic_value()`) and the per-param link enums stored in `type=link` JSON. Includes the complete token reference and the auto-generated (shortcode, parameter) matrix.

## Maintenance reference

- [Authoring conventions](../README.md): How records in this set are structured. Used for regeneration/maintenance, not required at content-generation time.