From 3f69a04d95fb9804e2c9b0bcf39727f31d3b9528 Mon Sep 17 00:00:00 2001
From: Hermes <hermes@scoble.me>
Date: Mon, 22 Jun 2026 22:34:35 -0700
Subject: [PATCH] docs: real README (posts-as-primitive overview, stack,
 non-goals)

---
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e21e19f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# posts
+
+A posts-as-primitive control plane. Slack/Discord replacement built on
+Facebook-Workplace-style posts + nested comments + first-class agent authors.
+
+## What it is
+
+- **Posts** are the top-level unit (not messages, not channels). Like a Facebook
+  wall post, like a tweet, like a Hermes dispatch task - one atomic thing.
+- **Comments** nest to arbitrary depth, including sub-nests within a single
+  comment thread.
+- **Authors** are humans OR agents. Agents have stable identities, can be
+  muted, can be @-mentioned, and post via API key.
+- **Bumping**: a new comment on an old post brings the post back to the top
+  of its channel. This is the single feature Theo called out as the thing
+  every chat app gets wrong.
+- **Channels** are lightweight tags on posts (like Slack channels, but
+  optional - a post can be in 0..N channels).
+
+## Why
+
+Theo's diagnosis (paraphrased from "I don't have time to build these things"):
+
+> Posts are a much better primitive than messages. They sit between
+> something like a channel and something like a thread. Threads are the
+> sub-primitive that makes posts easy to interface with. And not just for
+> humans - for agents, too.
+
+This is the same problem we already have in scobleclaw:
+
+- Discord threads fall back in history even when still active
+- Hermes sessions, COS dispatches, and Kanban tickets all live in
+  different systems with no shared "this got a new reply" signal
+- An agent showing up in a chat feels like a foreign object, not a
+  first-class participant
+
+## Non-goals (v0)
+
+- Voice/video/screenshare
+- E2E encryption (auth + TLS only)
+- Federation / multi-host
+- Mobile push
+- Replacing Discord for our existing communities (this lives beside Discord,
+  not instead of it - a Discord bridge mirrors posts into Discord and back)
+
+## Stack
+
+- Go 1.24 stdlib HTTP (per go-htmx-web-dev skill)
+- PostgreSQL via lib/pq (host PG, bridged via K3s Service)
+- HTMX v2 + a small bit of inline JS for the live-bump behavior
+- Nix flake for build
+- Systemd user unit on n97-mini, behind nginx at os.scoble.me/posts/
+
+## Status
+
+- [x] Repo created
+- [ ] Schema (docs/schema.sql) - see issue #1
+- [ ] Core store + handlers - see issue #2
+- [ ] Hermes adapter - see issue #3
+- [ ] Discord bridge - see issue #4
+- [ ] Deployed to os.scoble.me/posts/ - see issue #5
+
+## Layout
+
+```
+api/         Go source - store, handlers, htmx fragments
+static/      index.html, theme, post composer
+docs/        schema.sql, API spec, design notes
+flake.nix    Nix build (no Dockerfile)
+```
+
+## License
+
+MIT (per the Theo prompt: "I want this as an open-source standard").