add AUTOMATED_DEV.md: Gitea + Mattermost + CI + µPaaS pipeline

AUTOMATED_DEV.md

@@ -0,0 +1,249 @@
+# Automated Development Systems
+
+How we connect self-hosted Gitea, Mattermost, CI, and a lightweight PaaS into a
+continuous development pipeline where code goes from PR to production with
+minimal human intervention.
+
+---
+
+## The Hub: Self-Hosted Gitea
+
+[Gitea](https://gitea.io) is the coordination center. Every repo, issue, PR, and
+code review lives here. We self-host it because:
+
+- Full API access for automation (the agent has its own Gitea user with API
+  token)
+- Gitea Actions for CI (compatible with GitHub Actions syntax)
+- Webhooks on every repo event
+- No vendor lock-in, no rate limits, no surprise pricing changes
+- Complete control over visibility (public/private per-repo)
+
+The agent (OpenClaw) has its own Gitea account (`clawbot`) separate from the
+human user. This matters because:
+
+- The agent's commits, comments, and PR reviews are clearly attributed
+- The human can @-mention the agent in issues to assign work
+- Assignment is unambiguous — issues assigned to `clawbot` are the agent's
+  queue, issues assigned to the human are theirs
+- The agent can be given write access per-repo (some repos it can push to
+  directly, others it must fork and PR)
+- API rate limits and permissions are independent
+
+## Real-Time Activity Feed: Gitea → Mattermost
+
+Every repo has a Gitea webhook that sends all activity (pushes, PRs, issues,
+comments, reviews, CI status) to a channel in our self-hosted
+[Mattermost](https://mattermost.com) instance. This creates a real-time feed
+where everyone — human and agent — can see what's happening across all projects
+without cross-communication overhead.
+
+The agent also has its own Mattermost bot user (`@claw`), separate from the
+human. This means:
+
+- The agent posts status updates to dedicated channels (`#git` for Gitea work,
+  `#claw` for general work narration)
+- The human's DMs stay clean — only direct alerts and responses
+- In group channels, it's clear who said what
+- The agent can be @-mentioned in any channel
+
+### Channel Architecture
+
+A practical setup:
+
+- **#git** — Real-time Gitea webhook feed (all repos) + agent's work status
+  updates. Everyone sees commits, PRs, reviews, CI results as they happen.
+- **#claw** — Agent's internal work narration. Useful for debugging what the
+  agent is doing, but notifications muted so it doesn't disturb anyone.
+- **DM with agent** — Private conversation, sitreps, sensitive commands
+- **Project-specific channels** — For coordination with external collaborators
+
+The webhook feed in #git means nobody needs to check Gitea's notification inbox
+manually. PRs, reviews, and CI results flow into a channel that's always open.
+The agent monitors the same feed (via its notification poller) and can react to
+events in near-realtime.
+
+## CI: Gitea Actions
+
+Every repo has a CI workflow in `.gitea/workflows/` that runs on push. The
+standard workflow is one line:
+
+```yaml
+- name: Build and check
+  run: docker build .
+```
+
+Because the Dockerfile runs `make check` (which runs tests, linting, and
+formatting checks), a successful Docker build means everything passes. A failed
+build means something is broken. Binary signal, no ambiguity.
+
+### PR Preview Deployments
+
+For web projects (like a blog or documentation site), CI can go further than
+pass/fail. When a PR is opened against a site repo, CI can:
+
+1. Build the site from the PR branch
+2. Deploy it to a preview URL
+3. Post the preview URL as a comment on the PR or drop it into a Mattermost
+   channel
+
+This lets reviewers see the actual rendered result before merging, not just the
+code diff. For a Jekyll/Hugo blog, this means you can see how a new post looks
+on the real site layout, on mobile, with real CSS — before it goes live.
+
+## Deployment: µPaaS
+
+[µPaaS](https://git.eeqj.de/sneak/upaas) is a lightweight, self-hosted
+platform-as-a-service that auto-deploys Docker containers when code changes. It
+exists because:
+
+- Full PaaS platforms (Kubernetes, Nomad, etc.) are massive overkill for a small
+  fleet of services
+- Heroku/Render/Fly.io mean vendor dependency and recurring costs
+- We wanted: push to main → live in production, automatically, with zero human
+  intervention
+
+### How It Works
+
+µPaaS is a single Go binary that:
+
+1. **Receives Gitea webhooks** on push/merge events
+2. **Clones the repo** using deploy keys (read-only SSH keys per-repo)
+3. **Runs `docker build`** to build the new image
+4. **Swaps the running container** with the new image
+5. **Routes traffic** via Traefik reverse proxy with automatic TLS
+
+The deploy flow:
+
+```
+Developer merges PR to main/prod
+  → Gitea fires webhook to µPaaS
+    → µPaaS clones repo, builds Docker image
+      → µPaaS stops old container, starts new one
+        → Traefik routes traffic to new container
+          → Site is live on its production URL with TLS
+```
+
+Time from merge to live: typically under 2 minutes (dominated by Docker build
+time).
+
+### Deploy Keys
+
+Each repo that deploys via µPaaS has a read-only SSH deploy key. This means:
+
+- µPaaS can clone the repo to build it, but can't push to it
+- Each key is scoped to one repo — compromise of one key doesn't affect others
+- No shared credentials, no broad API tokens
+
+### What's Deployed This Way
+
+Any Docker-based service or site:
+
+- Static sites (Jekyll, Hugo) — Dockerfile builds the site, nginx serves it
+- Go services — Dockerfile builds the binary, runs it
+- Web applications — same pattern
+
+Everything gets a production URL with automatic TLS via Traefik.
+
+## The Full Pipeline
+
+Putting it all together, the development lifecycle looks like this:
+
+```
+1. Issue filed in Gitea (by human or agent)
+     ↓
+2. Agent picks up the issue (via notification poller)
+     ↓
+3. Agent posts "starting work on #N" to Mattermost #git
+     ↓
+4. Agent (or sub-agent) creates branch, writes code, pushes
+     ↓
+5. Gitea webhook fires → #git shows the push
+     ↓
+6. CI runs docker build → passes or fails
+     ↓
+7. Agent creates PR "(closes #N)"
+     ↓
+8. Gitea webhook fires → #git shows the PR
+     ↓
+9. Agent reviews code, runs make check locally, verifies
+     ↓
+10. Agent assigns PR to human when all checks pass
+     ↓
+11. Human reviews, requests changes or approves
+     ↓
+12. If changes requested → agent reworks, back to step 6
+     ↓
+13. Human merges PR
+     ↓
+14. Gitea webhook fires → µPaaS deploys to production
+     ↓
+15. Gitea webhook fires → #git shows the merge
+     ↓
+16. Site/service is live on production URL
+```
+
+Steps 2-10 can happen without any human involvement. The human's role is reduced
+to: review the PR, approve or request changes, merge. Everything else is
+automated.
+
+### Observability
+
+Because everything flows through Mattermost channels:
+
+- The human can glance at #git to see the current state of all projects
+- CI failures are immediately visible (Gitea Actions posts status)
+- Deployments are immediately visible (µPaaS can log to the same channel)
+- The agent's work narration in #claw shows what it's currently doing
+- No need to check multiple dashboards — one chat client shows everything
+
+## Identity Separation
+
+A key architectural decision: the agent has its own identity everywhere.
+
+| System     | Human Account | Agent Account |
+| ---------- | ------------- | ------------- |
+| Gitea      | @sneak        | @clawbot      |
+| Mattermost | @sneak        | @claw         |
+
+This separation means:
+
+- **Clear attribution.** Every commit, comment, and message shows who did it.
+  When reviewing git history, you know which commits were human and which were
+  agent.
+- **Independent permissions.** The agent can have write access to repos where
+  it's trusted, fork-and-PR access where it's not. The human can have admin
+  access without the agent inheriting it.
+- **Mentionability.** The human can @-mention the agent in an issue comment to
+  assign work. The agent can @-mention the human when it needs review. This
+  works exactly like human-to-human collaboration.
+- **Separate notification streams.** The agent's notification poller watches
+  `@clawbot`'s inbox. The human's notifications are separate. No cross-talk.
+
+## Why Self-Host Everything
+
+The stack — Gitea, Mattermost, µPaaS, OpenClaw — is entirely self-hosted. This
+isn't ideological; it's practical:
+
+- **No API rate limits.** The agent makes dozens of API calls per hour to Gitea.
+  GitHub's API limits would throttle it.
+- **No surprise costs.** CI minutes, seat licenses, storage — all free when
+  self-hosted.
+- **Full API access.** Every feature of every tool is available via API. No
+  "enterprise only" gates.
+- **Custom webhooks.** We can wire up any event to any action. Gitea push →
+  Mattermost notification → µPaaS deploy → agent notification, all custom.
+- **Data sovereignty.** Code, issues, conversations, and deployment
+  infrastructure all live on machines we control.
+- **Offline resilience.** If GitHub/Slack/Vercel have an outage, our pipeline
+  keeps running.
+
+The trade-off is maintenance burden, but with an AI agent handling most of the
+operational work (monitoring, updates, issue triage), the maintenance cost is
+surprisingly low.
+
+---
+
+_This document describes a production system that's been running since
+early 2026. The specific tools (Gitea, Mattermost, µPaaS) are interchangeable —
+the patterns (webhook-driven deployment, real-time activity feeds, identity
+separation, automated CI gates) apply to any self-hosted stack._

README.md

@@ -7,6 +7,11 @@ agent) under the direction of [@sneak](https://sneak.berlin).
 
 ## What's Here
 
+- **[AUTOMATED_DEV.md](AUTOMATED_DEV.md)** — How self-hosted Gitea, Mattermost,
+  Gitea Actions CI, and µPaaS connect into a continuous pipeline where code goes
+  from PR to production automatically. Covers webhook-driven deployments,
+  real-time activity feeds, PR preview sites, identity separation (agent vs
+  human accounts), and why self-hosting the entire stack matters.
 - **[OPENCLAW_TRICKS.md](OPENCLAW_TRICKS.md)** — Tested configuration recipes
   for OpenClaw agents: workspace bootstrapping, daily context state files,
   sitrep (situation report) prompts, sleep tracking, medication tracking,