Post a technical article to community.azcomputerguru.com (Flarum forum).

Converts markdown to Flarum's s9e TextFormatter XML format and inserts directly into the
database via paramiko SSH to IX. Shows a preview and waits for user confirmation before posting.

---

## Usage

```
/forum-post                    Draft interactively — Claude asks for title, content, tag
/forum-post <topic hint>       Claude drafts from conversation context, then confirms
```

Arguments are optional. With no args, Claude uses the current conversation context to
determine what to post (the most recent technical problem solved, fix documented, etc.).

---

## Infrastructure

| Item | Value |
|---|---|
| Forum URL | https://community.azcomputerguru.com |
| DB host | localhost (on IX) |
| DB name | azcompu_flarum |
| DB user | azcompu_flarum |
| DB pass | vault: `services/flarum-community.sops.yaml credentials.db_password` |
| IX SSH | root@172.16.3.10 — password from vault: `infrastructure/ix-server.sops.yaml credentials.password` |
| Admin user_id | 1 (MikeSwanson) |

Get the IX SSH password via vault before connecting:
```bash
bash "$CLAUDETOOLS_ROOT/.claude/scripts/vault.sh" get-field infrastructure/ix-server.sops.yaml credentials.password
```

---

## Known Tags

| tag_id | Name | When to use |
|--------|------|-------------|
| 7 | How-Tos & Tips | Technical fixes, how-tos, diagnostics, field notes |

To see all current tags: query `SELECT id, name_singular FROM tags;` on azcompu_flarum.
Default to tag_id=7 unless the user specifies otherwise.

---

## Phase 1: Gather Inputs

Collect in one pass — do not ask field by field:

1. **Title** — descriptive, search-friendly, sentence case. Include the technology/product.
   Good: `OneDrive KFM Fails After Folder Redirection Migration -- Here's What's Actually Going On`
   Bad: `OneDrive issue fix`

2. **Content** — full markdown body. Minimum useful length: 3-4 paragraphs with concrete detail.
   Write from the conversation context: what was the problem, what was tried, what actually worked, what to remember.

3. **Tag** — default How-Tos & Tips (7) unless user says otherwise.

Generate the slug from the title: lowercase, spaces/punctuation to hyphens, remove apostrophes,
collapse multiple hyphens. Max ~90 chars. Example:
`onedrive-kfm-fails-after-folder-redirection-migration-heres-whats-actually-going-on`

---

## Phase 2: Show Preview

Before posting, show:

```
FORUM POST PREVIEW
------------------
Title:  <title>
Tag:    How-Tos & Tips
Slug:   <slug>
URL:    https://community.azcomputerguru.com/d/<next_id>-<slug>

--- Content ---
<first 500 chars of markdown>
...

Post this? (yes/no)
```

Wait for explicit confirmation before executing.

---

## Phase 3: Execute

Write and run a Python script (use `py` on Windows). The script must:

1. **Get IX SSH password** from vault (see Infrastructure above)
2. **Connect via paramiko** (`AutoAddPolicy`, password auth)
3. **Generate the s9e XML** from the markdown (see Converter section below)
4. **Build the PHP insert script** (see PHP Template below)
5. **SFTP upload** the PHP script to `/tmp/flarum_post_<timestamp>.php` on IX
6. **Run** `php /tmp/flarum_post_<timestamp>.php 2>&1` via SSH
7. **Parse output** — look for `Discussion ID: N` and `Post ID: N`
8. **Clean up** — `rm /tmp/flarum_post_<timestamp>.php`
9. **Report** the live URL

---

## Markdown → s9e XML Converter

Flarum stores post content as s9e TextFormatter XML, not raw markdown. The stored format
must match what Flarum's TextFormatter produces. Based on confirmed existing posts:

### Inline elements

| Markdown | s9e XML |
|---|---|
| `**bold**` | `<STRONG><s>**</s>bold<e>**</e></STRONG>` |
| `*italic*` | `<EM><s>*</s>italic<e>*</e></EM>` |
| `` `code` `` | `<C><s>`</s>code<e>`</e></C>` |

XML-escape `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;` in all text content and code spans.

### Block elements

| Markdown | s9e XML |
|---|---|
| `## Heading` | `<H2><s>## </s>Heading</H2>` |
| `### Heading` | `<H3><s>### </s>Heading</H3>` |
| Paragraph | `<p>text</p>` |
| `- item` (list) | `<LIST><LI><s>- </s>item</LI>\n<LI>...</LI></LIST>` |
| `1. item` (ordered) | `<LIST type="decimal"><LI><s>1. </s>item</LI>\n...</LIST>` |
| ` ```lang ` fenced block | `<CODE lang="lang"><s>```lang</s><i>\n</i>code\n<e>```</e></CODE>` |

Block elements are separated by `\n\n` (two real newlines) inside the `<r>` root.
List items are separated by `\n` (one newline).
Entire content is wrapped: `<r>...</r>`.

### Python converter (copy this directly into the py script)

```python
import re

def xml_escape(t):
    return t.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')

def inline_to_xml(text):
    result = ''
    i = 0
    while i < len(text):
        if text[i:i+2] == '**':
            end = text.find('**', i+2)
            if end != -1:
                inner = inline_to_xml(text[i+2:end])
                result += '<STRONG><s>**</s>' + inner + '<e>**</e></STRONG>'
                i = end + 2; continue
        if text[i] == '`':
            end = text.find('`', i+1)
            if end != -1:
                result += '<C><s>`</s>' + xml_escape(text[i+1:end]) + '<e>`</e></C>'
                i = end + 1; continue
        if text[i] == '*' and text[i:i+2] != '**':
            j = i + 1; end = -1
            while j < len(text):
                if text[j] == '*' and text[j:j+2] != '**': end = j; break
                j += 1
            if end != -1:
                result += '<EM><s>*</s>' + xml_escape(text[i+1:end]) + '<e>*</e></EM>'
                i = end + 1; continue
        result += xml_escape(text[i]); i += 1
    return result

def md_to_s9e(md):
    lines = md.split('\n')
    elements = []
    i = 0
    while i < len(lines):
        line = lines[i]
        if not line.strip(): i += 1; continue
        if line.startswith('## '):
            elements.append('<H2><s>## </s>' + inline_to_xml(line[3:]) + '</H2>'); i += 1
        elif line.startswith('### '):
            elements.append('<H3><s>### </s>' + inline_to_xml(line[4:]) + '</H3>'); i += 1
        elif line.startswith('- '):
            items = []
            while i < len(lines) and lines[i].startswith('- '):
                items.append('<LI><s>- </s>' + inline_to_xml(lines[i][2:]) + '</LI>'); i += 1
            elements.append('<LIST>' + '\n'.join(items) + '</LIST>')
        elif re.match(r'^\d+\. ', line):
            items = []
            while i < len(lines) and re.match(r'^\d+\. ', lines[i]):
                m = re.match(r'^(\d+)\. (.*)', lines[i])
                items.append('<LI><s>' + m.group(1) + '. </s>' + inline_to_xml(m.group(2)) + '</LI>'); i += 1
            elements.append('<LIST type="decimal">' + '\n'.join(items) + '</LIST>')
        elif line.startswith('```'):
            lang = line[3:].strip(); code_lines = []; i += 1
            while i < len(lines) and not lines[i].startswith('```'):
                code_lines.append(xml_escape(lines[i])); i += 1
            i += 1
            tag = f'<CODE lang="{lang}">' if lang else '<CODE>'
            elements.append(tag + f'<s>```{lang}</s><i>\n</i>' + '\n'.join(code_lines) + '\n<e>```</e></CODE>')
        else:
            para_lines = []
            while i < len(lines) and lines[i].strip():
                l = lines[i]
                if l.startswith('## ') or l.startswith('### ') or l.startswith('- ') or l.startswith('```') or re.match(r'^\d+\. ', l): break
                para_lines.append(l); i += 1
            elements.append('<p>' + inline_to_xml('\n'.join(para_lines)) + '</p>')
    return '<r>' + '\n\n'.join(elements) + '</r>'
```

---

## PHP Insert Template

Use `%%XML_CONTENT%%` as the placeholder — replace with the generated s9e XML before uploading.
The closing nowdoc marker `FLARUM_POST_XML_END;` must be at column 0 with no leading whitespace.

```php
<?php
ini_set('display_errors', 1); error_reporting(E_ALL);
$dsn = 'mysql:host=localhost;dbname=azcompu_flarum;charset=utf8mb4';
$pdo = new PDO($dsn, 'azcompu_flarum', '<DB_PASS from vault services/flarum-community.sops.yaml>', [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);

$user_id = 1; $tag_id = %%TAG_ID%%;
$title   = %%TITLE_PHP%%;
$slug    = '%%SLUG%%';
$now     = date('Y-m-d H:i:s');

$content = <<<'FLARUM_POST_XML_END'
%%XML_CONTENT%%
FLARUM_POST_XML_END;

// Insert discussion first (post refs are nullable)
$stmt = $pdo->prepare("INSERT INTO discussions (title, comment_count, post_number_index, created_at, user_id, slug, is_private, is_approved) VALUES (?, 1, 1, ?, ?, ?, 0, 1)");
$stmt->execute([$title, $now, $user_id, $slug]);
$disc_id = $pdo->lastInsertId();
echo "Discussion ID: $disc_id\n";

// Insert post
$stmt = $pdo->prepare("INSERT INTO posts (discussion_id, number, created_at, user_id, type, content, is_private, is_approved) VALUES (?, 1, ?, ?, 'comment', ?, 0, 1)");
$stmt->execute([$disc_id, $now, $user_id, $content]);
$post_id = $pdo->lastInsertId();
echo "Post ID: $post_id\n";

// Link post back to discussion
$pdo->prepare("UPDATE discussions SET first_post_id=?, last_post_id=?, last_posted_at=?, last_posted_user_id=?, last_post_number=1 WHERE id=?")->execute([$post_id, $post_id, $now, $user_id, $disc_id]);

// Tag
$pdo->prepare("INSERT INTO discussion_tag (discussion_id, tag_id) VALUES (?, ?)")->execute([$disc_id, $tag_id]);

echo "Done! URL: https://community.azcomputerguru.com/d/$disc_id-$slug\n";
```

### Template substitutions

| Placeholder | How to fill |
|---|---|
| `%%TAG_ID%%` | Integer (e.g. `7`) |
| `%%TITLE_PHP%%` | PHP double-quoted string with escaped `"` — e.g. `"The Title Here"` |
| `%%SLUG%%` | URL-safe slug string |
| `%%XML_CONTENT%%` | The output of `md_to_s9e(content_md)` |

Build the PHP script in Python using `.replace()` — never f-strings (curly braces in XML content
will cause Python to try to expand them as template expressions).

---

## Paramiko Execution Pattern

```python
import paramiko, time

client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect('172.16.3.10', username='root', password=IX_PASS, timeout=10)

# Upload
remote_path = f'/tmp/flarum_post_{int(time.time())}.php'
sftp = client.open_sftp()
with sftp.open(remote_path, 'wb') as f:
    f.write(php_script.encode('utf-8'))
sftp.close()

# Execute
def run_chan(cmd):
    chan = client.get_transport().open_session()
    chan.exec_command(cmd)
    chan.shutdown_write()
    out = b''
    while not chan.exit_status_ready():
        if chan.recv_ready(): out += chan.recv(4096)
    while chan.recv_ready(): out += chan.recv(4096)
    return out.decode('utf-8', errors='replace'), chan.recv_exit_status()

out, rc = run_chan(f'php {remote_path} 2>&1')
run_chan(f'rm -f {remote_path}')
client.close()
```

---

## Error Handling

| rc | Symptom | Cause | Fix |
|---|---|---|---|
| 255, no output | Script crashes silently | Exception with display_errors off | Script already includes `ini_set('display_errors',1)` |
| FK constraint error | Cannot add child row | Post inserted before discussion | Use discussion-first insert order (template above does this) |
| Empty curl response | localhost curl returns nothing | HTTP→HTTPS redirect on vhost | Use paramiko PHP approach, not curl |
| Cloudflare challenge | API blocked externally | Bot protection | Always insert via paramiko, never via external HTTP |

---

## After Posting

Report:
```
[SUCCESS] Posted to community.azcomputerguru.com
Discussion: #<id>
URL: https://community.azcomputerguru.com/d/<id>-<slug>
Tag: How-Tos & Tips
```

Do NOT try to verify via curl or browser — Cloudflare blocks external API calls and
localhost curl has a redirect issue. The DB output is the authoritative confirmation.
