publish

# 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 Re-run the publish command with the same output path: ```bash gbrain publish brain/companies/acme.md --password "same-password" --out shares/acme.html ``` Same file, same URL (if hosted), updated content. ## Revoking Access Delete the file. If using signed URLs, the URL expires automatically (1 hour). If using static hosting, remove the file from the host. ## When it fails Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill: - The source page returns `page_not_found`: resolve the real slug first; never publish a guessed page. - `gbrain files upload` / `gbrain files signed-url` fails (storage not configured, `bucket_not_found`): tell the user publishing needs storage and run `gbrain doctor --json`; do not paste private page content instead. ## Anti-Patterns - **Publishing without encryption.** Brain content is private. Default to password-protected unless the user explicitly says "open", "no password", or "public". - **Sharing password and URL in the same channel.** Always share the password via a different channel than the URL for security. - **Assuming the user wants raw markdown.** The publish command produces beautiful HTML. Don't copy-paste markdown when `gbrain publish` exists. - **Including internal metadata.** Never manually share content that contains frontmatter, source citations, or timeline sections. Let the publish command strip it. ## Output Format ``` PUBLISHED: [page title] ======================== File: [output path] Encrypted: [yes (AES-256-GCM) / no] Password: [auto-generated password / user-provided / none] Size: [file size] Share the file via: [email / Slack / Airdrop / cloud upload] Share the password via: [a different channel] ``` ## Tools Used - `gbrain publish` -- deterministic HTML generation (no LLM calls) - `gbrain files upload` -- upload to cloud storage (optional) - `gbrain files signed-url` -- generate access links (optional)