docs: restructure roadmap and add plugin branch workflow rules

Stages now reflect architectural milestones only (Memory DB → Vault →
Skills → Daemon → Audit → Web UI). Plugins move to a perpetual catalog
with per-plugin git branches. Always-push rule replaces the old
no-push default. Adds Plugin Branches workflow section.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -7,8 +7,8 @@ a plugin/integration system (Stage 2+) and an encrypted vault (Stage 3+).
 
 ## Current Status
 
-**Stage 2.1 — Plugin Framework: complete** (2026-05-17)
+**Stage 2 — Plugin Framework: complete** (2026-05-18)
-Next: Stage 2.2 (Nextcloud plugin) + Stage 2.3 (Email plugin)
+Next: Stage 3 — Memory Database
 
 ## Project Roadmap
 
@@ -16,15 +16,7 @@ Next: Stage 2.2 (Nextcloud plugin) + Stage 2.3 (Email plugin)
 Working `pyra` executable with provider setup wizard, streaming chat REPL, .md-based
 memory in `~/.pyra/memory/`, and hard security boundaries around the vault.
 
-### Stage 2 — Plugin System & Integrations (IN PROGRESS)
+### Stage 2 — Plugin Framework ✅ COMPLETE
-
-Pyra runs as a system daemon so messaging bots are always-on. All integrations are
-standalone Python plugin scripts in `~/.pyra/plugins/` — not hardcoded in `src/pyra/`.
-The AI uses tool-use (function calling) to invoke plugins; every execution requires
-explicit user approval (y/N prompt). Plugin credentials are stored in the vault under
-namespaced keys (`plugin:{name}:{key}`).
-
-#### Stage 2.1 — Plugin Framework ✅ COMPLETE
 - `src/pyra/plugins/` package: `base.py`, `loader.py`, `registry.py`, `executor.py`, `install.py`
 - `src/pyra/bundled_plugins/` — ships bundled plugin scripts with pyra
 - `src/pyra/daemon/` stub (CLI surface only)
@@ -33,47 +25,60 @@ namespaced keys (`plugin:{name}:{key}`).
 - Chat session: AI tool-use loop (up to 10 iterations), approval gate, plugin slash commands
 - CLI: `pyra plugin list/install/enable/disable/setup`, `pyra daemon *` stubs
 
-#### Stage 2.2 — Nextcloud Plugin (next)
+### Stage 3 — Memory Database (next)
-Bundled plugin: `src/pyra/bundled_plugins/nextcloud/plugin.py`
+Replace the flat `.md` file scanner with SQLite + FTS5 for fast full-text search.
-CalDAV calendar, CardDAV contacts, WebDAV files.
+Schema designed to add a vector column later for semantic (embedding-based) search.
-Install deps: `uv pip install -e ".[nextcloud]"`
+Backwards-compatible: existing `.md` memory files are migrated on first run.
 
-#### Stage 2.3 — Email Plugin (next, parallel with 2.2)
+### Stage 4 — Vault Encryption
-Bundled plugin: `src/pyra/bundled_plugins/email/plugin.py`
-IMAP (Hotmail.de/Outlook), folder browsing, smart event extraction to calendar.
-No new deps (uses stdlib imaplib).
-
-#### Stage 2.4 — Daemon + Messaging Bots
-- `src/pyra/daemon/server.py` — asyncio event loop, plugin tasks, IPC socket
-- `src/pyra/daemon/ipc.py` — Unix socket (chmod 600), line-delimited JSON protocol
-- `src/pyra/daemon/service.py` — launchd plist (macOS) / systemd unit (Linux)
-- Bundled plugins: `matrix_bot`, `telegram_bot`, `signal_bot`
-- Security: sender allowlist, bcrypt passphrase challenge, rate limiting (20 msg/hr),
-  injection scanning on all incoming messages, tool approval over messaging (2-min timeout)
-
-#### Stage 2.5 — Infrastructure Plugins
-Bundled plugins: `ssh_tool` (paramiko), `docker_tool` (docker SDK),
-`kubernetes_tool` (kubectl subprocess), `service_manager` (systemctl/launchctl),
-`smb_mount` (mount subprocess)
-
-#### Stage 2.6 — Cloud Storage Plugins
-Bundled plugins: `gdrive` (Google OAuth2), `onedrive` (MSAL device flow), `dropbox_tool`
-
-### Stage 3 — Vault Encryption
 Encrypt `~/.pyra/vault/secrets/` using `age` (or GPG fallback). Pyra decrypts in memory
 at call time only — no plaintext ever written to disk after initial setup. Secret
 rotation support. Per-key passphrases optional.
 
-### Stage 4 — Security Audit Sub-agent
+### Stage 5 — Skills System
-A separate `pyra security audit` command that spins up a sandboxed AI agent whose sole
+YAML-defined multi-plugin workflows with event triggers and AI-driven selection.
-job is scanning for vulnerabilities: prompt injection in memory files, unexpected vault
+Skills compose existing plugin tools into automated pipelines with conditional branching
-access attempts in `security.log`, outdated dependency CVEs, permission drift on `~/.pyra/`.
+and human-in-the-loop decision points.
+
+### Stage 6 — Daemon + Messaging Bots
+Always-on asyncio daemon, IPC socket, launchd/systemd service. Bundled bots:
+`matrix_bot`, `telegram_bot`, `signal_bot`. Sender allowlist, bcrypt passphrase
+challenge, rate limiting (20 msg/hr), injection scanning on all incoming messages,
+tool approval over messaging (2-min timeout).
+
+### Stage 7 — Security Audit Sub-agent
+`pyra security audit` — sandboxed agent scanning for prompt injection in memory files,
+unexpected vault access in `security.log`, outdated CVEs, permission drift on `~/.pyra/`.
 Report written to `~/.pyra/security_audit.md` (not AI-readable during normal chat).
 
-### Stage 5 — Web UI / Advanced Features
+### Stage 8 — Web UI / Advanced Features
 Optional local web interface (FastAPI + HTMX or similar). Embedding-based memory search
-(ChromaDB or sqlite-vec). Scheduled automations via cron-style plugin scheduling.
+via `sqlite-vec`. Multi-profile support (work vs personal).
-Multi-profile support (work vs personal).
+
+---
+
+### Plugin Catalog (not stage-gated — ships when ready)
+
+Plugins are developed independently on `plugin/<name>` branches and merged to `main`
+only when complete. All integrations are standalone Python plugin scripts in
+`~/.pyra/plugins/` — not hardcoded in `src/pyra/`. Plugin credentials are stored in
+the vault under namespaced keys (`plugin:{name}:{key}`).
+
+| Plugin | Branch | Status |
+|--------|--------|--------|
+| `nextcloud` | `plugin/nextcloud` | planned |
+| `email` | `plugin/email` | planned |
+| `websearch` | `plugin/websearch` | planned |
+| `headless_browser` | `plugin/headless_browser` | planned |
+| `server_manager` | `plugin/server_manager` | planned |
+| `matrix_bot` | `plugin/matrix_bot` | planned |
+| `telegram_bot` | `plugin/telegram_bot` | planned |
+| `signal_bot` | `plugin/signal_bot` | planned |
+| `ssh_tool` | `plugin/ssh_tool` | planned |
+| `docker_tool` | `plugin/docker_tool` | planned |
+| `gdrive` | `plugin/gdrive` | planned |
+| `onedrive` | `plugin/onedrive` | planned |
+| `dropbox_tool` | `plugin/dropbox_tool` | planned |
 
 ---
 
@@ -250,7 +255,18 @@ chore: description
 - **One commit per concern.** If a session touches a file for two different reasons (e.g. a bugfix and a cleanup), those are two separate commits — staged and committed independently, even if the file is the same.
 - Use the project commit convention: `feat(module):`, `fix(module):`, `test:`, `docs:`, `chore:` followed by a short description.
 - Always `git add` only the files relevant to that commit — never `git add .` blindly.
-- Do **not** push unless explicitly asked to.
+- **Always push after committing** — every commit goes to the remote Gitea repository immediately.
+
+### Plugin Branches
+
+- Every plugin is developed on its own branch: `plugin/<name>` (e.g. `plugin/nextcloud`).
+- A plugin branch is **never merged to `main` until the plugin is complete and tested**.
+- `main` always contains only production-ready core source code (`src/pyra/` framework).
+- If plugin work uncovers a bug in core Pyra code, fix it on a dedicated `fix/...` branch
+  off `main`, commit it to `main`, push, then rebase the plugin branch onto the updated `main`.
+- Plugin branches may be pushed to remote for backup/review at any time.
+- Do **not** merge plugin branches to `main` prematurely — a half-working plugin on `main`
+  is worse than one that isn't there yet.
 
 ### Avoid Duplication — Check the Inventory First