diff --git a/README.md b/README.md index 8b07a3d..4afc7da 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,164 @@ -# MPM Brand Voice Plugin +# mpm-brand-voice -Keeps every piece of AI-generated content aligned with Message Point Media's voice, tone, messaging pillars, and visual identity. Brand settings are baked in — works immediately in any working folder with no setup required. +Keeps every piece of AI-generated content aligned with Message Point Media's voice, tone, messaging pillars, and visual identity. Brand settings, the full logo catalog (PNG + SVG), and the Montserrat/Open Sans fonts are baked into the plugin payload — logos and fonts load instantly with no Google Drive or Google MCP fetch required. Works immediately in any working folder, no setup. + +**Version:** 1.2.1 +**Author:** Message Point Media +**Repo:** https://git.mpm.to/mpm/mpm-brand-voice-plugin +**CoWork Project:** CW-001 — MPM Brand Voice + +--- + +## Overview + +The MPM Brand Voice plugin gives Claude a persistent, structured understanding of how Message Point Media communicates. It ships with a fully baked-in `settings/brand-voice.local.md` file containing MPM's complete brand identity — 11 messaging pillars, 6 audience personas, voice constants, tone matrix, product terminology, logo system, color palette, and typography references. As of v1.2.1, the plugin also bakes in the full MPM logo catalog (24 PNG/JPG + 40 SVG variants under `assets/logos/`) and the Montserrat/Open Sans variable font files (`assets/fonts/`), so logo and font lookups never require the Google Drive connector or Google MCP at runtime — the Drive folders remain the upstream source of truth but are no longer needed for day-to-day content generation. A working-folder override (`.claude/brand-voice.local.md`) can be placed in any project folder to supply project-specific positioning (e.g., a co-branded proposal) that takes precedence over the baked-in defaults. The plugin exposes two skills: one for applying the guidelines to content creation, and one for enriching the guidelines from new source materials. + +--- ## Skills -### Brand Voice Enforcement -Apply MPM's brand guidelines to any content you're creating. - -**Trigger phrases:** "write an email", "draft a proposal", "create a pitch deck", "write a LinkedIn post", "write in our voice", "make this sound like MPM", "this doesn't sound on-brand" - -The skill loads the baked-in MPM brand settings via `bash cat` (required — the Read tool cannot access `.remote-plugins` paths) and applies them to your content — voice constants, tone adjustments for your audience, correct product terminology, and messaging pillar alignment. If the settings file is unreachable, the skill stops and surfaces an explicit error rather than falling back silently to generic styling. It explains the brand choices it made and offers to refine. - -**v1.1.0 additions:** Logo selection table and placement rules for DOCX/PPTX/PDF/email. Explicit Visual Identity block — Montserrat headings, Open Sans body, exact hex color palette. Warning against generic blue (#1A4F8A) and system fonts (Arial, Calibri). - -### Guideline Generation -Update or enrich MPM's brand settings from new source materials. - -**Trigger phrases:** "update our brand settings", "analyze these materials for brand voice", "add this content to our guidelines", "generate brand guidelines from these documents" - -Use this when you have new conference presentations, sales transcripts, updated messaging, or new product documentation that should be reflected in the brand settings. The skill builds on the existing settings rather than replacing them. +| Skill | What It Does | +|---|---| +| `brand-voice-enforcement` | Applies MPM brand guidelines to any AI-generated content. Loads brand settings via `bash cat` on `settings/brand-voice.local.md` (required — the Read tool silently fails on `.remote-plugins` paths; a failed read is a hard stop, never a silent fallback), identifies the content type and target audience persona, selects relevant messaging pillars, applies voice constants and tone flexes, resolves the correct baked-in logo file via the Logo Selection Rules table, generates content, and validates the output. Trigger phrases include: "write an email", "draft a proposal", "create a pitch deck", "write a LinkedIn post", "draft a presentation", "write a Slack message", "draft sales content", "on-brand", "brand voice", "enforce voice", "apply brand guidelines", "brand-aligned content", "write in our voice", "use our brand tone", "make this sound like MPM", "rewrite this in our tone", "this doesn't sound on-brand". Not for generating guidelines from scratch — use `guideline-generation` for that. | +| `guideline-generation` | Generates or updates MPM brand voice guidelines from source materials — uploaded files (PDF, PPTX, DOCX, MD, TXT), discovery reports, working folder documents, Google Drive files, or direct user input. Always loads existing `brand-voice.local.md` before generating; builds on what exists rather than replacing it wholesale. Applies confidence scoring and source classification (Authoritative / Strong Signal / Supporting / Context Only). Trigger phrases include: "generate brand guidelines", "update our brand settings", "create a style guide", "extract brand voice", "analyze these materials for brand voice", "build guidelines from these documents", "synthesize a voice and tone guide", "update brand-voice.local.md", "add this content to our brand settings". Not for applying guidelines to content creation — use `brand-voice-enforcement` for that. | --- -## How Brand Settings Work +## Tools Reference -The plugin ships with `settings/brand-voice.local.md` — the full MPM brand settings file. This is the baked-in default that works in any working folder. +This is a skill-only plugin — no MCP server, no external API calls. All processing is done by Claude using the baked-in skill prompts, settings, and asset files. -> ⚠️ **Read method matters:** The `Read` tool cannot access `.remote-plugins` paths and fails silently. The brand-voice-enforcement skill uses `bash cat` to read the settings file. If it cannot be read, the skill stops and tells you — it will never silently produce generic output. - -**Priority order when a skill loads settings:** -1. `.claude/brand-voice.local.md` in the current working folder (project-specific override, if present) -2. Plugin's `settings/brand-voice.local.md` (this file — always available) - -For most projects, the baked-in settings are all you need. Use a working folder override only when a specific project requires different positioning (e.g., a co-branded proposal, a specific sub-brand focus). +| Skill | Reference Files | +|---|---| +| `brand-voice-enforcement` | `settings/brand-voice.local.md`, `references/voice-constant-tone-flexes.md`, `references/before-after-examples.md`, `references/mpm-brand-resources.md`, `../../assets/README.md` | +| `guideline-generation` | `settings/brand-voice.local.md`, `references/guideline-template.md`, `references/confidence-scoring.md`, `references/mpm-brand-resources.md` | --- -## Keeping Settings Current +## Baked-In Assets (new in v1.2.1) -The MPM brand evolves. When it does: +`assets/logos/png/` — 24 raster logos (PNG/JPG) for documents, web, presentations, email. +`assets/logos/svg/` — 40 vector logos (SVG) for print and large-format. +`assets/fonts/` — Montserrat (headings) and Open Sans (body) variable fonts, plus their SIL Open Font License files. +`assets/README.md` — full asset manifest: logo quick-pick table, directory layout, and the filename-normalization mapping back to the original Drive names (spaces/`@`/`[]` stripped for plugin-packaging safety). -1. **Update the master** — Edit `.claude/brand-voice.local.md` in the Claude CoWork working folder on Google Drive. This is always the source of truth. -2. **Repackage the plugin** — Open Cowork, select the Claude CoWork folder, and ask Claude to "repackage the MPM brand voice plugin with the updated settings." -3. **Push to the org library** — Upload the new `.plugin` file to the organization plugin library. +Resolve any asset path relative to `${CLAUDE_PLUGIN_ROOT}`, e.g. `${CLAUDE_PLUGIN_ROOT}/assets/logos/png/Logo-Standard-Dark.png`. Always confirm a path with `ls` before handing it to a document tool. + +### Logo Selection Rules + +| Background | Logo to Use | File (in `assets/logos/png/`) | +|---|---|---| +| White or light backgrounds | Standard Dark (DEFAULT) | `Logo-Standard-Dark.png` | +| White / off-white backgrounds | Gold + Black text | `Logo-Gold-Black.png` | +| Dark, charcoal, or dark-gold backgrounds | Gold + White text | `Logo-Gold-White.png` | +| Cover pages, title blocks with dark header bar | Gold + White text | `Logo-Gold-White.png` | +| Single-color black print | Black text only | `Logo-Black-Text.png` | +| Dark background, icon only needed | White Cutout | `Logo-White-Cutout.png` | + +For print and large-format output, use the matching SVG from `assets/logos/svg/`. Transit-specific deliverables use the TransitPoint sub-brand lockup (`MPM-Transitpoint-Dark.png` / `MPM-Transitpoint-Light.png`). --- -## CoWork Project +## Setup Instructions -**CW-001 — MPM Brand Voice** -- Drive folder: https://drive.google.com/drive/folders/1v38nIYfda_VanCHFbIU9BDk_7H4ENtbO -- Wiki: https://docs.google.com/document/d/1dTKG6t2Fjbg16wsoY2Nd0Sd8zDZ8TT-0KgXD_o8uksY/edit +No server to run, no environment variables required. The plugin is self-contained. + +**Step-by-step:** +1. Obtain `mpm-brand-voice-v1.2.1.plugin` from the CW-001 Drive coordination folder +2. Open CoWork and navigate to Plugin settings +3. Click "Install Plugin" and select the `.plugin` file +4. Restart CoWork to activate +5. Verify by asking Claude to "write a short email in our voice" — it should reference MPM brand attributes, use a baked-in logo, and produce on-brand content without any additional setup + +### Setup Checklist +- [ ] `.plugin` file obtained from CW-001 Drive folder +- [ ] Plugin installed via CoWork Plugin settings +- [ ] CoWork restarted +- [ ] Test content generation confirms brand settings and baked-in logo/font assets loaded + +--- + +## Connection Details + +| Field | Value | +|---|---| +| Plugin type | Skill-only (no MCP server) | +| Transport | None (no external API) | +| Auth method | None required | +| Settings file | `settings/brand-voice.local.md` (baked-in) | +| Asset payload | `assets/logos/` (64 files), `assets/fonts/` (baked-in, no Drive fetch) | +| Working folder override | `.claude/brand-voice.local.md` (optional, project-specific) | + +--- + +## Workflow Notes + +**Brand Settings Priority Order** +When a skill loads settings, it checks in this order and stops at the first match: +1. `.claude/brand-voice.local.md` in the current working folder (project-specific override) +2. `settings/brand-voice.local.md` baked into the plugin (always available) +3. Brand guidelines generated earlier in the session via `guideline-generation` + +**Voice vs. Tone** +Voice is WHO the brand is — it never changes. Tone is HOW it speaks in a given moment — it flexes along three dimensions: Formality (High/Medium/Low), Energy (High/Medium/Warm/Low), and Technical Depth (High/Medium/Low). The skill applies the correct tone matrix for the content type and audience automatically. + +**Content Type Guidance** +- Cold outreach: Medium formality, High energy, Low depth — hook fast, earn attention +- Enterprise proposals: High formality, Medium energy, High depth — ROI and precision +- Social media: Low-Medium formality, High energy, Low depth — brevity and personality +- Customer success: Medium formality, Warm energy, Medium depth — empathy and competence + +**Conference Language** +"Born to Innovate. Built to Last." is the primary tagline for standard use. Motorsports/race-themed language (pit stop, velocity, etc.) is MPower 2025 conference-specific. The skill will flag use of this language outside that context and offer the standard brand equivalent. + +**Keeping Settings and Assets Current** +When the MPM brand evolves: +1. Update the master — edit `.claude/brand-voice.local.md` in the Claude CoWork working folder on Google Drive, or update the baked-in `settings/brand-voice.local.md` source directly for a plugin-wide change +2. If logos or fonts changed, re-pull the affected files from the MPM Logos Drive folder into `assets/` and re-run the filename normalization in `assets/README.md` +3. Repackage — ask Claude to "repackage the MPM brand voice plugin with the updated settings" +4. Push to org library — upload the new `.plugin` file; team members will see an update available + +--- + +## Brand Document Locations (Google Drive) + +| Document | Location | +|---|---| +| MPM Brand Guide (.docx / .pdf) | Design Guide folder | +| MPM Logo Guide (.docx / .pdf) | Design Guide folder | +| MPM Brand Deck (.pptx) | Design Guide folder | +| Logo files (PNG / SVG) — upstream source of truth | MPM Logos → 01 New Logos | +| Fonts — upstream source (Google Fonts originals) | 02 MPM Branding → Fonts | +| Zoom backgrounds, templates | 02 MPM Branding | + +Design Guide: https://drive.google.com/drive/folders/1-H19hqC6HUX_3FjjrRVAoimg688CldrC +Logos: https://drive.google.com/drive/folders/1xpO_sh0dQvWiMQbdmbhRZARuev4RpZiL + +--- + +## Requirements + +- CoWork (Claude Desktop with plugin support) +- No external dependencies, API keys, or environment variables + +--- + +## Troubleshooting + +| Symptom | Fix | +|---|---| +| Content doesn't reflect MPM voice | Confirm plugin is installed and CoWork was restarted after install | +| Wrong brand settings loaded | Check for a `.claude/brand-voice.local.md` in the working folder — it overrides the plugin defaults | +| Guideline generation overwrites existing settings | The skill should enrich, not replace. If it replaced, restore from the `brand-voice.local-YYYY-MM-DD.md` backup the skill creates before saving | +| Conference/race language appearing in standard content | The skill should flag this — if it didn't, ensure you're using the `brand-voice-enforcement` skill, not a generic Claude response | +| Logo file can't be resolved | Confirm `${CLAUDE_PLUGIN_ROOT}` is set and run `ls` on `assets/logos/png/` to diagnose; never substitute a non-MPM logo — use the labeled placeholder pattern in `brand-voice-enforcement/SKILL.md` instead | --- ## Version History | Version | Date | Notes | -|---------|------|-------| -| 1.1.0 | May 2026 | Patched brand-voice-enforcement: bash cat required for settings read (Read tool silently fails on .remote-plugins); hard stop on read failure. New Logo Usage section with selection table, placement rules, and fallback behavior. Visual Identity block with explicit font/hex requirements and warning against generic blues/system fonts. | -| 1.0.0 | March 2026 | Initial release. Full MPM brand settings including MPower 2025 conference content, complete logo catalog, font references, 11 messaging pillars, 6 audience personas, and product terminology. | - -**Author:** Message Point Media | mpmedia.tv +|---|---|---| +| 1.2.1 | 2026-07-01 | Full MPM logo catalog (64 files) and Montserrat/Open Sans variable fonts baked into `assets/` — eliminates Google Drive/Google MCP fetch for logos and fonts at runtime. New `assets/README.md` manifest with filename-normalization mapping. `SKILL.md` updated to resolve asset paths via `${CLAUDE_PLUGIN_ROOT}`. Keywords updated (added logos, fonts, offline-assets). | +| 1.1.0 | 2026-05-21 | `bash cat` fix for brand settings read (Read tool silently fails on `.remote-plugins` — hard stop on failure). Logo Usage section added to `SKILL.md` with selection table, placement rules, and fallback behavior. Visual Identity block added to Quick Reference with Montserrat/Open Sans requirements and full hex palette. | +| 1.0.0 | 2026-05-05 | Initial release. Full MPM brand settings including MPower 2025 conference content, complete logo catalog, font references, 11 messaging pillars, 6 audience personas, and product terminology. |