# Greyhaven Brand Voice & Messaging -- Claude Skill

> **Source of truth**: `vibedocs/greyhaven-brand-system.md` (Brand Guidelines v1.1)
>
> This skill applies when generating ANY user-facing content for Greyhaven:
> marketing copy, landing pages, CTAs, product descriptions, documentation,
> email, README intros, explanations of how the product works, or any prose
> that will be read by a human. It does NOT apply to internal code comments,
> commit messages, or technical logs.

---

## 1. The One-Line Test

Before writing any sentence, ask:

> Would an engineer who understands the system read this and feel it's accurate, direct, and free of hype?

If no, rewrite. That single test catches 90% of brand drift.

---

## 2. Core Positioning (memorize)

**Greyhaven builds custom, contained AI systems that run entirely inside the client's environment, shaped by real operational constraints and deployed under the client's control.**

**Short form**: *Local-first AI systems shaped by real work. Built where work happens. Contained end to end.*

Powered by Monadical's internal, open-source stack, hardened over eight years.

---

## 3. The Three Brand Axes

Every sentence, heading, or visual choice should land on the correct side of these three axes. When in doubt, use them to explain *why* something is wrong without relying on taste.

| Axis | Greyhaven is on this side | NOT this side |
|------|---------------------------|---------------|
| **Containment** | Systems run inside the perimeter. Nothing leaks. | Cloud/SaaS narratives. "Connected everywhere." |
| **Human-centered** | Built around how people actually work. | Built around model capabilities or vendor features. |
| **Engineered** | From real deployments, constraints, operator reality. | Vision-first, theatrical, speculative, futuristic. |

If copy drifts toward **exposure, performance, or model-led thinking → it doesn't fit**.

---

## 4. Tone of Voice

**Direct. Plain-spoken technical. Explains difficult things in simple terms.**

Greyhaven speaks like an engineer who understands how systems work and can describe them cleanly -- without mystique or theatrics.

- **No** jargon for its own sake
- **No** oversimplification
- **No** sales language
- **No** hype adjectives ("revolutionary", "cutting-edge", "seamless", "powerful", "game-changing")
- **No** evangelism ("unleash", "empower", "transform")
- **No** emotional leverage or fear-mongering
- **Yes** calm, precise, explanatory
- **Yes** mechanical facts
- **Yes** specifics over superlatives
- **Yes** authority through clarity, not volume

---

## 5. Writing Rules

### 5.1 Explain clearly. Don't perform.

The goal is clarity, not persuasion. Readers have different levels of technical know-how. Describe what happens inside the environment, how data flows, which dependencies matter, what boundaries exist. If something is complex, break it down without dumbing it down.

### 5.2 Plain-language engineering

Use everyday words for technical realities. If a simpler word communicates the same thing, use it.

| Instead of | Prefer |
|-----------|--------|
| "data paths" | "where the data goes" |
| "surfaces" | "places where exposure/risk can happen" |
| "dependencies" | "things the system relies on" |
| "isolation" | "kept separate from the outside" |
| "logs" | "records of what happened" |
| "handoffs" | "when one person/system passes something to another" |
| "leverage" | "use" |
| "leverage AI to..." | "the system uses AI to..." |
| "synergy" | (don't use) |
| "cutting-edge solution" | (don't use) |
| "transform your workflow" | describe what the system does instead |

Don't assume the reader knows technical shorthand. The reader should leave with a clearer mental model, not an impressed feeling.

### 5.3 Human-first in how we describe work

Start from what operators actually do -- steps, judgment calls, knowledge. Explain operator behaviors the same way you explain systems: concretely and without dramatization.

### 5.4 Security, stated without drama

Mechanical facts, not alarmism.

- **Good**: "Running inside the perimeter restores finite boundaries."
- **Bad**: "Protect your data from devastating breaches!"

State causal reasoning. No emotional leverage.

### 5.5 Quiet confidence

State specifics. No hype adjectives. No evangelism. Authority comes from clarity, not volume.

- **Good**: "A working, testable prototype delivered in 24-48 hours."
- **Bad**: "Lightning-fast, industry-leading AI delivery!"

---

## 6. Patterns for Reasoning

Use these four patterns to structure explanations. They express engineering logic: minimal wording, direct causality, observable/verifiable outcomes.

### Cause → Effect
> "When work relies on external AI services, every step -- inputs, outputs, logs, metadata -- becomes part of someone else's infrastructure."

### Constraint → Outcome
> "No external APIs and no data leaving the environment. The system remains contained, and the client keeps full operational and security control."

### Observation → Explanation
> "We sit with the operators, map the steps, and build a system that mirrors what actually happens."

### Finite Scope → Concrete Result
> "One process at a time. A working, testable prototype delivered in 24-48 hours."

---

## 7. CTA Guidance

Greyhaven CTAs should be concrete and engineering-flavored, not aspirational or urgent.

**Good CTA patterns**:
- "See how it runs in your environment"
- "Map your first process"
- "Review the architecture"
- "Read how it's deployed"
- "Get a working prototype in 48 hours"

**Avoid**:
- "Unlock the power of AI"
- "Transform your business today"
- "Don't miss out!"
- "Revolutionary AI solutions await"
- Urgency/scarcity framing ("limited time", "hurry", "act now")
- Hype verbs ("unleash", "supercharge", "revolutionize")

---

## 8. Driving Ideas (use these to self-check)

A sentence, heading, or design choice should feel like one of these:

> **(System-)aware · Applied · Adaptable · Unblocking · Safe-to-experiment · Contained · Durable · Iterative**

If it doesn't land on any of them, or lands somewhere else (flashy, theatrical, aspirational), rewrite.

---

## 9. Typography Approach (for written-content UI)

Hierarchy is built through **tonal shifts**, not decorative treatments.

- Primary points stay **dark and controlled** (foreground text)
- Supporting detail **moves lighter** (muted-foreground)
- The orange accent is **reserved** for parts that require immediate attention -- never decorative

Do NOT establish hierarchy through:
- Multiple contrasting typefaces
- Decorative styles (italics for emphasis, ALL CAPS for drama, oversized type for style)
- Color variety

DO establish hierarchy through:
- Weight differences within the same family (serif for content, sans for UI)
- Shade shifts between foreground, muted-foreground, and the orange accent
- Spatial rhythm (section padding, line-height)

This keeps the system quiet, structured, and readable.

---

## 10. Logo Usage

### Available files (in `public/logos/` after install)

| File | Use when |
|------|----------|
| `gh-logo-positive-full-black.svg` | Full logo (symbol + wordmark) on light backgrounds |
| `gh-logo-white.svg` | Full logo on dark backgrounds |
| `gh-logo-offblack.svg` | Full logo in off-black (#161614) for warm-neutral contexts |
| `gh-symbol-full-black.svg` | Symbol only, light bg (use when name recognition is already established) |
| `gh-symbol-full-white.svg` | Symbol only, dark bg |
| `greyproxy-positive.svg` | Greyproxy product logo (Greyhaven symbol + product wordmark) |
| `greywall-positive.svg` | Greywall product logo (Greyhaven symbol + product wordmark) |

### Rules

- **Structure**: The logo is **Symbol + Wordmark**. Keep them locked together in most contexts. Use the Symbol alone only when Greyhaven name recognition is already assured.
- **Clearspace**: Minimum 1× (one grid module of the symbol) on all sides. Nothing -- text, images, other graphics -- enters this zone.
- **Minimum sizes**:
  - Wordmark lockup: 20mm print / 120px digital
  - Standalone symbol: 8mm print / 14px digital (22px preferred)

### What to avoid (all of these are brand violations)

- Do NOT change opacity
- Do NOT apply new colors (black, white, off-black only -- per file)
- Do NOT stretch or alter proportions
- Do NOT apply gradients, shadows, glows, or other embellishments
- Do NOT rotate
- Do NOT change the lockup or alter symbol/wordmark relative scale

### Product logos

New Greyhaven products/demos reuse the Greyhaven symbol with the product wordmark in the same lockup pattern (see `greyproxy-positive.svg`, `greywall-positive.svg`). Typography for new wordmarks: Circular Medium. Do NOT invent a new symbol unless the product genuinely needs its own sub-identity.

---

## 11. Self-check Before Shipping Any Copy

Run the output through these checks:

1. ☐ Does it pass **The One-Line Test** (accurate, direct, no hype)?
2. ☐ Does it land on the correct side of all **three brand axes** (containment, human-centered, engineered)?
3. ☐ Did I use any **banned words** (unleash, transform, revolutionary, seamless, game-changing, cutting-edge, leverage, synergy, unlock)?
4. ☐ Is every claim **specific and verifiable**, or am I using vague superlatives?
5. ☐ Does the copy **explain how the thing works**, or just tell the reader how to feel about it?
6. ☐ Does it match a **reasoning pattern** (cause→effect, constraint→outcome, observation→explanation, finite scope→concrete result)?
7. ☐ Does it fit one of the **driving ideas** (system-aware, applied, adaptable, unblocking, safe-to-experiment, contained, durable, iterative)?
8. ☐ Is the orange accent used only where immediate attention is warranted, not as decoration?

If any box is unchecked, rewrite.

---

## 12. Quick Examples

### Bad vs. Good: Hero headline

| Bad | Good |
|-----|------|
| "Unleash the power of AI in your organization" | "AI systems that run inside your environment" |
| "Revolutionary cloud-native AI platform" | "Custom AI, contained end to end" |
| "Transform your workflows with next-gen AI" | "Map one process. Deploy a working prototype in 48 hours." |

### Bad vs. Good: Feature description

**Bad**:
> Our cutting-edge AI seamlessly integrates with your existing infrastructure to unlock unprecedented productivity gains.

**Good**:
> The system runs on the machines you already have. Data, models, and execution stay inside your perimeter. Nothing is sent to external APIs.

### Bad vs. Good: CTA

| Bad | Good |
|-----|------|
| "Get started today!" | "Map your first process" |
| "Try it free -- limited time!" | "Review the architecture" |
| "Unlock AI superpowers" | "See a 48-hour prototype" |

---

## 13. When You're Unsure

Default to:
1. **Fewer words**. Greyhaven copy is shorter than you expect.
2. **More specifics**. Numbers, concrete nouns, named constraints.
3. **Less enthusiasm**. No exclamation marks. No superlatives. No urgency.
4. **Describe the system, not the feeling**.
