publish

Files (1)

• SKILL.md

SKILL.md (first lines)

# Publish Skill

Share brain pages as beautiful, self-contained HTML documents. Optionally
password-protected with client-side AES-256-GCM encryption. No server needed.

This is a **code + skill pair**: the deterministic code (`gbrain publish`) does
the stripping, encrypting, and HTML generation. This skill tells you when and
how to use it. See [Thin Harness, Fat Skills](https://x.com/garrytan/status/2042925773300908103)
for the architecture philosophy.

## Contract

- Published HTML is fully self-contained: no external dependencies, no server needed.
- All private metadata (frontmatter, source citations, confirmation numbers, brain cross-links, timeline) is stripped before publishing.
- Password protection uses AES-256-GCM with PBKDF2 key derivation; plaintext never appears in the encrypted HTML file.
- Default is always encrypted unless the user explicitly requests "open", "no password", or "public".
- External URLs (`https://...`) are preserved; only internal brain paths are stripped.

## When to Publish

- User asks to share a brain page, create a shareable link, or says "give me a page"
- User wants to send a deal memo, person briefing, or research to someone external
- User asks to publish a data room analysis or trip plan
- Any time brain content needs to leave the brain without exposing the whole system

## Default: ALWAYS ENCRYPT

Brain content is private. Default to password-protected unless the user explicitly
says "open", "no password", or "public".

If no password is specified, auto-generate one. Share the password via a different
channel than the URL.

## Quick Reference

```bash
# Basic publish (outputs local HTML file)
gbrain publish brain/companies/acme.md

# Password protected (auto-generate password)
gbrain publish brain/companies/acme.md --password

# Password protected (specific password)
gbrain publish brain/companies/acme.md --password "secret123"

# Custom title
gbrain publish brain/companies/acme.md --password --title "Acme -- Deal Analysis"

# Custom output path
gbrain publish brain/companies/acme.md --out /tmp/acme-share.html
```

## What Gets Stripped

The publish command automatically removes all private/internal data:

| Stripped | Example | Why |
|---------|---------|-----|
| YAML frontmatter | `title:`, `type:`, `tags:` | Internal metadata |
| `[Source: ...]` citations | All formats | Provenance is internal |
| Confirmation numbers | `ABC123DEF` -> "on file" | PII/booking data |
| Brain cross-links | `[Jane](../people/jane.md)` -> `Jane` | Internal paths |
| Timeline section | Everything below `---` / `## Timeline` | Raw evidence log |
| "See also" lines | Internal references | Brain navigation |

**Preserved:** external URLs (`https://...`), all other content.

## Sharing Workflows

### Option A: Local file (simplest)

```bash
gbrain publish brain/people/jane-doe.md --password --out ~/Desktop/jane-briefing.html
```

Share the HTML file via email, Slack, Airdrop. Share the password separately.

### Option B: Upload to cloud storage

```bash
# Publish locally first
gbrain publish brain/companies/acme.md --password "secret" --out /tmp/acme.html

# Upload to Supabase Storage
gbrain files upload /tmp/acme.html --page shares/acme

# Get a signed URL (1-hour expiry)
gbrain files signed-url shares/acme/acme.html
```

Share the signed URL + password. URL expires in 1 hour. Re-generate as needed.

### Option C: Static hosting (Render, Netlify, S3)

Upload the HTML file to any static hosting service. The file is self-contained,
no server logic needed. Password-protected files work entirely client-side via
Web Crypto API.

### Option D: GitHub Pages / Gist

```bash
gbrain publish brain/trips/japan-2026.md --out trip.html
# Upload to a GitHub Gist or Pages repo
```

## Password Protection Details

- **Algorithm:** AES-256-GCM
- **Key derivation:** PBKDF2 with 100K iterations, SHA-256
- **Salt:** Random 16 bytes per encryption
- **IV:** Random 12 bytes per encryption
- **Decryption:** Client-side via Web Crypto API (SubtleCrypto)
- **No server auth needed** -- the HTML file is self-contained
- **"Remember on this device"** -- saves password in localStorage

When encrypted, the published HTML contains ONLY ciphertext. The plaintext is
not present anywhere in the file.

## Updating a Published Page

From weareturnone/gbrain, MIT.