Brand

Track which fields in the firm section were explicitly set by the user — this matters for logo suppression and website rendering rules.

Step 3: Apply natural-language overrides

Check the resolved config for "nl_overrides": false. If false, skip this step entirely and log: "NL overrides disabled (nl_overrides: false)."

Otherwise, check if {WORKING_DIR}/.claude/branding.local.md exists. If it does:

1. Read the file content as natural-language instructions.
2. Interpret each instruction into concrete brand-config values.
3. Precedence rule: NL overrides may only set fields that were NOT explicitly set in the JSON override. JSON always wins.
4. Log each NL interpretation: what the instruction said, what field it mapped to, what value was chosen.

Examples of NL interpretation:

• "Use a warm earth-tone palette" → interpret as specific hex values for colors.primary, colors.accent, etc.
• "Company name is Terra Holdings" → set firm.name to "Terra Holdings"
• "Use serif fonts for headings" → set typography.font_family_heading to "Georgia, serif"

Step 4: Derive semantic and component tokens

This step runs AFTER NL overrides so that any NL color changes are reflected in derived tokens.

For any field in the semantic section that is not explicitly set (by defaults, JSON, or NL), derive it from the final resolved colors:

For any field in the components section that is not explicitly set:

Other component tokens (card_radius, card_shadow, callout_border_width, footer_height, header_height, logo_max_height) keep their defaults if not overridden.

Step 5: Resolve assets

Check for asset overrides in {WORKING_DIR}/.reporting/:

Logo suppression rule: If firm.name was overridden (via JSON or NL) but no custom logo.png exists in .reporting/, do NOT copy the default Acme logo. An overridden firm name with a mismatched logo is worse than no logo. Log: "Logo suppressed — firm.name overridden but no custom logo provided."

Website rendering rule: If firm.name was overridden but firm.website was NOT explicitly set in the user's JSON override, do not render firm.website in any output. The default Acme URL must never appear alongside a non-Acme firm name.

Step 6: Write .reporting-resolved/

Delete {WORKING_DIR}/.reporting-resolved/ entirely if it exists. Never merge incrementally with a prior run — full replacement prevents stale values from persisting.

Then create .reporting-resolved/ and write:

1. brand-config.json — the fully resolved configuration with all 8 sections + top-level flags. Include an _office_scripts_path field set to the absolute path of ${CLAUDE_PLUGIN_ROOT}/scripts/office/ — this tells generators where to find the office utilities without copying them.
2. brand-resolution-log.md — audit trail documenting:
   • Which defaults were used
   • Which JSON fields were overridden (list each field and new value)
   • Which NL instructions were interpreted (original text → field → value)
   • Whether NL overrides were disabled
   • Whether logo was suppressed and why
   • Timestamp of resolution
3. Asset files — resolved logo.png, logo-dark.png, icon.png, watermark.png (or note which were suppressed).

Note: office scripts (soffice.py, pack.py, unpack.py, validate.py, helpers/) are NOT copied. They are static files that live in the branding plugin at ${CLAUDE_PLUGIN_ROOT}/scripts/office/. Generators find them via the _office_scripts_path field in the resolved brand-config.json.

Step 7: Confirm

Report to the user what was resolved:

• Firm name and branding source (defaults / JSON override / NL override)
• Whether strict mode or NL-disable is active
• Number of assets resolved
• Path to .reporting-resolved/

Output Conventions

All generators must follow these output rules. Include this section's rules when instructing generators.

Directory structure

All output goes to {WORKING_DIR}/output/ with subdirectories per format:

File naming

Pattern: {slug}-{YYYY-MM-DD}-{HHmm}-{xxx}.{ext}

• slug: Kebab-case, alphanumeric and hyphens only. Strip or replace slashes, spaces, special characters, and non-ASCII. Example: q1-performance-report.
• YYYY-MM-DD: Date of generation.
• HHmm: 24-hour time of generation (hours and minutes).
• xxx: 3-character random hex suffix to prevent same-minute collisions.
• ext: Format-appropriate extension.

Example: quarterly-review-2026-04-04-1430-a8f.pdf

Exception: Interactive apps use descriptive directory names without timestamps (output/app/q1-dashboard/). Re-running overwrites the previous version.

Provenance

Each generated file should include a meta.sources section (where the format supports it) listing the data sources used during generation.