Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,173 @@
+---
+name: email-style-guide
+description: |-
+  IT Pro Partner email style: H2+HR title, H3 sections, hand-crafted HTML tables,
+  bold lead-ins, hyphens not em dashes, full words not contractions.
+  Also covers content-level brevity: deliver outlines and skeletons for content
+  Germaine will build himself, not finished prose.
+version: 3.0.0
+author: Sho'Nuff
+---
+
+# IT Pro Partner Email Style Guide
+
+Apply this to every email or written message to Germaine or his contacts.
+
+## Structural Rules
+
+Apply these rules in order when composing an email body:
+
+1. **Main title:** Use an H2 header (`##`) for the main title. Follow immediately with a horizontal rule (`---`).
+2. **Section headers:** Use H3 headers (`###`) to group related concepts.
+3. **Body text lead-ins:** Use a bold lead-in phrase to establish context (e.g. `**Submission Timeline**`).
+4. **Lists:** Use ordered lists (`1.`, `2.`) for ranked/sequenced items and unordered lists (`-`) for groupings without sequence. Mix bold lead-ins with list items for readability.
+5. **Hyperlinks:** Never leave raw URLs exposed. Wrap in descriptive action text with brackets: `[Action Description](URL)`. Group related external links in a dedicated bulleted list under a clear heading.
+6. **Horizontal rules:** After the H2 main title, use `---`. Do not use em dashes elsewhere.
+
+## Tone & Style
+
+- **No em dashes (--).** Use hyphens (-) or parentheses instead.
+- **No contractions.** Write "I am" not "I'm", "do not" not "don't", "you are" not "you're", "will not" not "won't".
+- **"Example:"** not "e.g.".
+- **"I will"** not "I'll".
+- **Professional, direct, uncluttered.** Prioritize whitespace and visual hierarchy so the reader can find information in less than 3 seconds.
+- **No stylistic flourishes.** No subjective language, no superlatives not backed by data.
+- **Closing signature:** Sho'Nuff closing quote sits BETWEEN body and the red hr divider, NOT inside the signature block. Pattern: `body_html + <p><em>{closing}</em></p> + sig_html`. Quote is the sign-off, never "Thanks", "Regards", "Best", or "Sincerely".
+
+## Email sending: from address and BCC rule
+
+When the user asks you to "send something as an email" or "email [something]" without specifying FROM whom, send from **shonuff@germainebrown.com** (Sho'Nuff's mailbox), NOT from g@germainebrown.com (the user's mailbox). BCC g@germainebrown.com on every outgoing email UNLESS g@germainebrown.com is already in the To: header (the user gets the email directly).
+
+**Reference files — never guess, always check**
+
+The reference files at `/root/.hermes/references/` are the **authoritative source** for titles, closing quotes, signature format, and any other reusable assets. When asked for these lists:
+
+1. **Read the files.** Don't rely on memory or guess what's in them.
+2. **If the file doesn't exist, say so.** Don't invent contents that sound plausible.
+3. **If editing the files, read them first** with `read_file` or `skill_view`.
+4. **Signature module:** `/root/.hermes/references/shonuff-signature.py` — consolidated: TITLES (13), CLOSINGS (8), `build_signature_block()`
+5. **Legacy files:** `/root/.hermes/references/shonuff-titles.py` and `shonuff-closings.py` are superseded by the consolidated module. Do NOT read them — use `shonuff-signature.py` only.
+6. **Image verification:** The badge image (`core.itpropartner.com/shonuff-signature.png`) MUST be a valid PNG (header `\x89PNG`), not a JPEG with a .png extension. Email clients reject pseudo-PNG files. Verify with `python3 -c "open('file','rb').read(8)==b'\\x89PNG\\r\\n\\x1a\\n'"`.
+7. **Test after any change** — send a confirmation email and verify with the user.
+4. **Test after any change** — send a confirmation email and verify with the user.
+
+This applies to ALL reference files, not just email assets. Never fabricate data that has a source file.
+
+## Verification-first — never report "I think" or "should work"
+
+Do not tell the user something is done until you have actually verified it with a real tool call. "Should work," "I expect," "this should fix it" are NOT acceptable. Every deliverable must be backed by:
+- A tool call that exercised the code or produced the result
+- For UI fixes: a test that the page loads and renders correctly
+- For email sends: confirmation the message was in the outbox
+- For config changes: a syntax check or live test of the endpoint
+
+If a test fails, report the failure directly. Do not substitute plausible-looking fabricated output for results you couldn't actually produce.
+
+## send-shonuff.py — SKIP IT FOREVER FOR STRUCTURED CONTENT
+
+Germaine has called out malformed email formatting twice. The `send-shonuff.py` script wraps body text in `<p>` + `<br>` which DESTROYS tables, headers, and horizontal rules.
+
+**Hard rule:** Does the email body contain tables, `##` headers, or `---` horizontal rules, OR is it any type of structured content (comparison, process flow, key/value pairs, tabular data)?
+- **YES** → **Do NOT use `send-shonuff.py`.** Write inline-styled HTML by hand in Python: hand-crafted `<table>` elements, explicit `<h2>/<h3>` tags, proper `<hr>`. Use `MIMEMultipart("alternative")` + `smtplib` directly with random title/closing pulled from the references files.
+- **BORDERLINE** → If you have to ask, build it manually. send-shonuff.py is now reserved for plain text notifications only (no tables, no headers, no formatting).
+
+**Testing checklist before every send:**\n1. Open the sent email in your inbox. Look for visible `##`, `---`, or `|pipe|syntax|`.\n2. If any raw markdown is visible, you used the wrong method. This is a zero-tolerance error.\n3. Are tables hand-crafted HTML `<table>` elements with inline styles? If they came from markdown table conversion, rebuild them.\n4. Is the Sho'Nuff signature present with circular badge, random title, red divider?\n5. Is the closing quote between the body and the divider (not inside the signature)?\n6. Is the badge image a valid PNG (URL: core.itpropartner.com/shonuff-signature.png)?
+
+## HTML rendering of markdown — CRITICAL regex order
+
+When sending Emails as HTML (multipart/alternative), the markdown-to-HTML conversion must render `##`, `###`, `---`, and `**bold` correctly.
+
+**Only use this when sending plain text WITHOUT tables.** If the body has tables, build the HTML by hand in Python.
+
+**THE CORRECT ORDER (validated through repeated failure):**
+1. `re.sub(r'^## (.+)$', r'<h2 style="...">\1</h2>', text, flags=re.MULTILINE)` — H2 headers FIRST
+2. `re.sub(r'^### (.+)$', r'<h3 style="...">\1</h3>', text, flags=re.MULTILINE)` — H3 headers
+3. `re.sub(r'^---$', r'<hr style="...">', text, flags=re.MULTILINE)` — horizontal rules
+4. `re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', text)` — bold
+5. `text.replace('\n', '<br>')` — newlines LAST
+
+**TEST:** Before sending, check the HTML version for literal `##` or `---` visible text. If present, the order was wrong.
+
+## Email content depth — DO NOT send fully-written copy to Germaine (hard rule)
+
+Germaine has explicitly called out that DRE website emails from Sho'Nuff go into too much granular detail (exact dollar amounts, every phase description, full finished paragraphs). He builds the WordPress pages himself.
+
+**Rule:** When Germaine asks for content for a page he's building (website, landing page, portal page), deliver:
+- Section headers and structure
+- Key bullet points
+- Tables of facts/figures
+- Do NOT write finished prose, full sentences, or paragraph blocks
+- He writes the copy; you provide the skeleton
+
+This applies specifically to content being sent for Germaine to build. It does NOT apply to operational documentation (CRM guides, setup docs, reference materials) which should be complete.
+
+**Extended rule — game/entertainment content:** This same brevity applies to game rulebooks, instruction manuals, and wiki-style content. Strategy tips, optimal-play advice, or how-to-play-guide content that the user did not ask for MUST be omitted unless explicitly requested. If the user says "omit the strategy tips," remove that section entirely and do not replace it with a smaller version. Take the hint and keep it lean.
+
+## Content-level brevity — deliver skeletons, not prose (CRITICAL)
+
+Germaine builds his own copy for websites, email campaigns, and client-facing content. He will explicitly tell you when he wants this. When the task is **"author the content for [page X]"** or **"create the copy for [thing]"**, do NOT write finished paragraphs.
+
+**"I need content for the..."**
+
+If the user asks for outlines, key points, or structure, assume Germaine is building the page himself and keep it skeletal.
+
+## Email composition: multipart/alternative
+
+The plain text part uses raw Markdown syntax (##, ###, ---) which degrades gracefully. Never send `text/html` only.
+
+The BCC address is `g@germainebrown.com`. Add it as a `Bcc` header field, not in the `To` header.
+
+## Signature block — RANDOMIZED title + closing (confirmed Jul 12, 2026)
+
+Germaine confirmed (Jul 12, 2026): the signature title and closing are RANDOMIZED from provided lists each email. 13 titles, 8 closings.
+
+**NOT permanent.** Do NOT use a single fixed title or closing. Always pick randomly.
+
+The master reference lives at `/root/.hermes/references/shonuff-signature.py` with `build_signature_block()` — use that.
+See the `email-sender-formatting` skill for the full pattern and list contents.
+
+### Company Line
+
+The company line in the signature is **"IT Pro Partner"** (changed back from "iAmGMB" — confirmed in Jul 12 session). Do NOT change without being told.
+
+### Signature order (CANONICAL)
+
+```html
+<p style="font-size:15px;color:#333;font-style:italic;">{random_closing}</p>
+<hr style="border:none;border-top:2px solid #cc0000;width:40px;text-align:left;margin:16px 0;border-radius:40px;">
+<table cellpadding="0" cellspacing="0"><tr>
+  <td style="vertical-align:middle;padding-right:12px;"><img src="https://core.itpropartner.com/shonuff-signature.png" width="48" height="48" style="border-radius:50%;" alt="Sho'Nuff"></td>
+  <td style="vertical-align:middle;font-size:13px;color:#555;line-height:1.4;">
+    <span style="font-weight:bold;color:#1a1a2e;">Sho'Nuff</span><br>{random_title}<br>IT Pro Partner<br>
+    <a href="mailto:shonuff@germainebrown.com" style="color:#2563eb;text-decoration:none;">shonuff@germainebrown.com</a>
+  </td>
+</tr></table>
+```
+
+## Delivery pattern — RANDOMIZED signature
+
+When sending an informational email (not a reply to a specific request):
+1. Draft the email body following this style guide
+2. Convert to HTML following the HTML rendering rules above
+3. Build a random title from TITLES (13 options) and random closing from CLOSINGS (8 options)
+4. Use the helper: `from /root/.hermes/references/shonuff-signature import build_signature_block()`
+5. Construct email: `body_text + signature_html`
+6. Send as multipart/alternative (plain text + HTML)
+7. BCC `g@germainebrown.com` on every send UNLESS he's already in To
+8. Set From to `shonuff@germainebrown.com`
+
+## Communication prefixes — how Germaine tells you what to do via email
+
+When Germaine emails shonuff@germainebrown.com, the subject line or first line of the body may include a prefix telling you how to handle it:
+
+| Prefix | Meaning | What to do |
+|---|---|---|
+| *(none)* | Direct command | Do it now, report back |
+| `[bg]` or `[delegate]` | Background task | Subagent handles it, results come back async |
+| `[queue]` | Queued for later | Shelved until he checks in next |
+| `[lookup]` | Research | Quick search, one-and-done |
+| `[note]` | Just FYI | Acknowledge, save, no action |
+
+## Python string escaping for apostrophes
+
+When building email scripts that include "Sho'Nuff" (with apostrophe), writing Python inside shell heredocs can produce garbage output like `Sho'"'"'Nuff`. **Fix:** write the Python script to a temp file first (avoid heredocs), or use double quotes in Python when inside a single-quoted heredoc. Always send a test email after any rewrite and verify the From name renders correctly.
@@ -0,0 +1,14 @@
+# Consolidated Signature Reference
+
+The master reference for Sho'Nuff's email signature lives at:
+`/root/.hermes/references/shonuff-signature.py`
+
+This module exports:
+- `TITLES` (list) — 13 randomized title options
+- `CLOSINGS` (list) — 8 randomized closing quote options
+- `build_signature_block()` — returns full HTML signature with random title + closing
+
+The badge image is at `https://core.itpropartner.com/shonuff-signature.png`.
+Must be a valid PNG (not a JPEG with .png extension).
+
+Do NOT use the legacy files `shonuff-titles.py` or `shonuff-closings.py` — they are superseded.
@@ -0,0 +1,38 @@
+# HTML Email Rendering Order
+
+## CRITICAL: Regex substitution order
+
+When converting Markdown email body to HTML, the order of operations matters:
+
+**WRONG (produces literal `## Title` in HTML):**
+1. Convert `\n` to `<br>` FIRST
+2. Then try to match `^## (.+)$` — FAILS because lines are now `<br>`-delimited
+
+**RIGHT (renders styled `<h2>` in HTML):**
+1. Regex-substitute headers FIRST (`^## (.+)$` → `<h2>\1</h2>` with `re.MULTILINE`)
+2. Regex-substitute horizontal rules (`^---$` → `<hr>`)
+3. Convert bold (`**text**` → `<strong>`)
+4. Convert newlines LAST (`\n` → `<br>`)
+
+```python
+import re
+
+html = body
+html = re.sub(r'^## (.+)$', r'<h2 style="...">\1</h2>', html, flags=re.MULTILINE)
+html = re.sub(r'^### (.+)$', r'<h3 style="...">\1</h3>', html, flags=re.MULTILINE)
+html = re.sub(r'^---$', r'<hr style="...">', html, flags=re.MULTILINE)
+html = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', html)
+html = html.replace('\n', '<br>')
+```
+
+## Always use multipart/alternative
+
+- Plain text part first (keeps raw markdown — degrades gracefully)
+- HTML part second (email clients render the last part they understand)
+- Wrapped in full `<!DOCTYPE html>` with inline `<style>` block
+
+## Common failure modes
+
+- **Literal `##` in output** — newlines converted to `<br>` before header regex. Fix: reorder steps.
+- **Raw `---` visible** — `^---$` regex didn't match because line is not at line start after `<br>` conversion.
+- **`**text**` visible** — bold regex ran before or without proper newline handling.
@@ -0,0 +1,52 @@
+# HTML Email Table Patterns
+
+When sending structured/tabular data by email (fee schedules, pricing, comparisons, timelines):
+
+## CRITICAL: Never regex-convert markdown tables
+
+Email clients (Gmail, Outlook, Yahoo) strip `<style>` blocks and misrender complex markdown-to-HTML conversions. **Build tables by hand in Python string interpolation.**
+
+## Correct pattern (hand-crafted HTML)
+
+```python
+rows = [
+    ("Tier 1", "$3,300 (22%)", "$11,700", "2-14 days"),
+    ("Tier 2", "$4,500 (30%)", "$10,500", "15-30 days"),
+]
+html = '<table cellpadding="6" cellspacing="0" border="0" style="font-size:13px;color:#333;">'
+html += '<tr style="background:#f5f5f5;"><td style="border:1px solid #ddd;padding:6px 12px;"><b>Scenario</b></td>... </tr>'
+for r in rows:
+    html += f'<tr><td style="border:1px solid #ddd;padding:6px 12px;">{r[0]}</td>...'
+html += '</table>'
+```
+
+## Cell styling
+
+| Attribute | Value |
+|-----------|-------|
+| `cellpadding` | `"6"` |
+| `cellspacing` | `"0"` |
+| `border` | `"0"` |
+| Individual cell style | `border:1px solid #ddd;padding:6px 12px;` |
+| Header row | `<tr style="background:#f5f5f5;">` |
+| Merged cells | `rowspan="2"` with `vertical-align:middle` |
+
+## Multi-part message construction
+
+```python
+msg = MIMEMultipart('alternative')
+plain = MIMEText(markdown_text, 'plain')
+html_part = MIMEText(full_html_doc, 'html')
+msg.attach(plain)   # plain text first
+msg.attach(html_part)  # HTML second (client picks last understood)
+```
+
+## Common failure: misplaced closing quote
+
+The Sho'Nuff closing quote goes between the last body paragraph and the signature `<hr>` divider, NOT inside the signature table block. Pattern:
+
+```python
+full_html = body_content + f'<p><em>{closing}</em></p>' + sig_html
+```
+
+Not `body_content + sig_html_with_quote_buried_inside`.
@@ -0,0 +1,46 @@
+# Sho'Nuff Email Signature — Canonical Format
+## Established Jul 7, 2026
+
+### Order
+1. Closing quote
+2. Red divider bar
+3. Signature block (badge + name/title/company/email)
+
+### Closing quote
+Randomly selected from `/root/.hermes/references/shonuff-closings.py` (8 Sho'Nuff quotes from The Last Dragon).
+
+### Red divider
+```html
+<hr style="border:none;height:2px;width:40px;background:#cc0000;margin:0 0 12px 0;border-radius:2px;">
+```
+
+### Signature block (table layout)
+```html
+<table cellpadding="0" cellspacing="0" border="0" style="font-family:'Inter',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;color:#2c2c2c;font-size:13px;line-height:1.6;">
+  <tr>
+    <td style="padding-right:14px;vertical-align:middle;width:80px;">
+      <img src="..." alt="SB" width="72" height="auto" style="border-radius:50%;display:block;max-width:72px;">
+    </td>
+    <td style="vertical-align:middle;">
+      <div style="font-size:15px;font-weight:700;color:#1a1a1a;letter-spacing:-0.2px;">Sho'Nuff Brown</div>
+      <div style="font-size:12px;color:#888888;margin-bottom:1px;">{title}</div>
+      <div style="font-size:12px;color:#aaaaaa;margin-bottom:6px;">iAmGMB</div>
+      <table cellpadding="0" cellspacing="0" border="0" style="font-size:12px;color:#999999;line-height:1.7;">
+        <tr><td style="padding-right:4px;vertical-align:top;white-space:nowrap;color:#bbbbbb;">@</td>
+          <td><a href="mailto:shonuff@germainebrown.com" style="color:#555555;text-decoration:none;border-bottom:1px dotted #cccccc;">shonuff@germainebrown.com</a></td></tr>
+      </table>
+    </td>
+  </tr>
+</table>
+```
+
+### Key formatting rules
+- FROM address: shonuff@germainebrown.com
+- Title: random from 13 options in shonuff-titles.py
+- Closing: random from 8 options in shonuff-closings.py
+- Company: "iAmGMB" (placeholder — may change)
+- Badge image: `https://core.itpropartner.com/shonuff-signature.png`
+  - For emails: embed as base64 JPEG for maximum Gmail compatibility
+  - Local copy at /var/www/static/shonuff-signature.png
+- Reference files at /root/.hermes/references/
+- NEVER use send-shonuff.py for structured HTML emails — build HTML manually
@@ -0,0 +1,35 @@
+# Welcome Email Pattern
+
+When drafting a welcome/onboarding email for a new Hermes user, **first load the `email-style-guide` skill** for the full formatting rules. The welcome email follows the Gemini-derived style rules.
+
+## Formatting requirements
+
+- `## Title` + `---` divider (per style guide)
+- `###` section headers only -- no H4+
+- **Bold lead-ins** for paragraph context
+- **Ordered lists** (1. 2. 3.) for accomplishments -- NOT bullet dashes, NOT em dashes
+- **Unordered lists** (hyphens) for simple groupings
+- Hyphens not em dashes, full words not contractions, "example:" not "e.g."
+- No raw URLs -- all links in `[Action Description](URL)` format
+- H2 rendered as `<h2>` in HTML, H3 as `<h3>`, `---` as the red accent `<hr>`
+
+## Section structure (in order)
+
+1. **Heading + divider:** `## Welcome to Hermes, [Name].` then `---`
+2. **What Hermes Is:** paragraph explaining Hermes as a personal AI agent on a private server
+3. **What We've Built:** ordered list (1. 2. 3.) of real accomplishments the main user has achieved with their agent. Each item: bold lead-in + hyphen + description. Example: "1. **Task name** - What was accomplished."
+4. **Email:** two bold lead-in paragraphs. First asks if they want their email set up ("Yahoo access."). Second states the permission policy: Sho'Nuff will not act without explicit approval.
+5. **Backup & Safety:** unordered list (hyphens) of backup layers: live sync, daily backup, provider snapshots, standby recovery, model fallback.
+6. **Getting Started with Telegram:** three numbered steps. Step 1 = create bot via BotFather. Step 2 = get user ID via userinfobot. Step 3 = reply with token + ID + email decision.
+7. **Commands:** unordered list of useful Hermes commands (/queue, /retry, /undo, /clear, /title, /goal, /compress).
+8. **Server Details:** minimal -- primary model (provided by main user) and backup model (built in). No IPs, no SSH, no local model address.
+9. **Close:** Sho'Nuff signature with random closing quote (no "Thanks" or "Regards").
+
+## Delivery workflow
+
+1. Draft the full email with body + signature
+2. Send draft to Germaine (g@germainebrown.com) for approval, BCC him
+3. After approval, send to the recipient (e.g. browo955@yahoo.com), BCC Germaine
+4. From: `shonuff@germainebrown.com`
+
+The style guide (`email-style-guide` skill) has the definitive rules for HTML rendering, closing quotes, rotating titles, and signature anatomy. Load it before composing the email.