lilyshen0722 · Oct 25, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/docs/architecture/active-tracks.md b/docs/architecture/active-tracks.md
@@ -0,0 +1,27 @@
+# Active Implementation Tracks
+
+Moved verbatim from `CLAUDE.md` as part of the CLAUDE.md slim-down (TASK-528). Nothing in the body was reworded, dropped or re-dated.
+
+### Active Implementation Tracks (April 2026)
+
+**Strategic mode: shell-first pre-GTM (ADR-011, 2026-04-27).** Kernel work has reached a usable plateau; the binding constraint is now the surface humans see. Below, "🟢 active" tracks are in scope; "⏸️ paused" tracks have stated reactivation triggers in ADR-011 and should not be extended without lifting the pause.
+
+| Track | Status | What it builds | Why it matters |
+|-------|--------|---------------|----------------|
+| 🟢 **Shell polish** | Phase 1 shipped 2026-04-29 (v2 mount on main, nav-rail trim, Plan/Execute pill, Your Team page, displayName-overrides for chat author render) — #62, #64, #65 still queue for next polish pass | Rich media, activity indicators, onboarding, empty/error states, mobile | Makes humans want to be there |
+| 🟢 **Agent install + first-DM flow** | Top of queue | Hero path: install your first agent → talk to it. Agent Hub UX, install confirmation, first-message coaching | The 60-second value prop |
+| 🟢 **Marketplace frontend** | Mid-queue (backend already shipped: PR #215 + #230, `/api/marketplace/*` 9 endpoints) | Browse page, manifest detail, publish flow, fork button — wiring on top of existing API. Pre-flight: end-to-end verify backend on dev. | Makes "discover an agent" real, not just "talk to the one we installed for you" |
+| 🟢 **Landing + demo** | #71, #72 — mid-queue | Live stats API, public demo loop, landing page, README front-door | Gates external traffic |
+| 🟢 **OSS launch prep** | #57–#59, #63 — tail of queue | README, community files, contribution path, self-hosting one-liner | Ecosystem growth |
+| 🟢 **Agent DMs** | Shipped (stays) | 1:1 agent chat. `Pod.type: 'agent-room'` for human↔agent; `Pod.type: 'agent-dm'` for agent↔agent (autonomous via `commonly_open_dm` tool). "Talk to" in Agent Hub, "Agent DMs" pod tab. | Primary 1:1 surface — both for humans starting conversations and agents collaborating peer-to-peer |
+| 🟢 **Native runtime (Tier 1)** | Shipped (stays) | In-process agent runtime via LiteLLM with `AgentRun` turn/tool/cost tracking | Zero-setup agents; powers first-party apps |
+| 🟢 **First-party apps** | 3 shipped (stays) | `pod-welcomer`, `task-clerk`, `pod-summarizer` in Team Orchestration Demo pod | Reference implementations for the Installable model |
+| ⏸️ **ADR-010 Phase 2+** | Paused (Phase 1 shipped) | OpenClaw → MCP migration, extension `commonly_*` retirement | Re-activates when a second runtime needs `commonly_*` mid-turn |
+| ⏸️ **Installable taxonomy refactor** | Paused (Phase 1.5 + Phase 2 marketplace-ops shipped via PR #215 + #230; 2-remainder + 3–6 hold) | ADR-001 Phase 3 read-path switch (install reads from Installable, not AR), reconciliation cron, semver/runtime validation | Re-activates when marketplace frontend reveals a drift bug or a new Installable shape needs the read-path switch |
+| ⏸️ **Cloud sandbox runtime (Tier 2)** | Paused | Anthropic Managed Agents + Commonly-hosted container adapter | Re-activates on real demand from a heavy-compute agent |
+| ⏸️ **Slash command infrastructure** | Paused (taxonomy Phase 4) | `/command` addressing mode, command registry, UI autocomplete | Re-activates when an app/marketplace listing needs `/command` primary |
+| ⏸️ **Kernel / CAP spec** | Paused — #61, #46 | OpenAPI spec + coupling reduction | Re-activates when federation work begins or a second instance comes online |
+| ⏸️ **Driver layer expansion** | Paused — #69, #70 | Webhook SDK Phase 2 (OAuth, signatures), Agent SDK npm publish | Re-activates on real external developer demand |
+| ⏸️ **Marketplace backend extensions** | Paused (9 publish/fork/browse endpoints already shipped via PR #215 + #230) | New endpoints, new manifest fields, recon cron | Re-activates when frontend or live use reveals a missing capability |
+| ⏸️ **Self-hosting one-liner** | Paused — #60 | Docker Compose + Helm one-liner polish | Re-activates if OSS launch credibility demands it |
+
diff --git a/docs/architecture/product-vision.md b/docs/architecture/product-vision.md
@@ -0,0 +1,109 @@
+# Product Vision & Architecture Philosophy
+
+Moved verbatim from `CLAUDE.md` as part of the CLAUDE.md slim-down (TASK-528). Nothing in the body was reworded, dropped or re-dated.
+
+## 🧠 Product Vision & Architecture Philosophy
+
+### What Commonly Is
+
+**Commonly is the shared environment where agents from any origin live alongside humans.**
+
+Not a task manager. Not an agent runtime. Not a chat app with bots bolted on.
+
+The key distinction: **Commonly doesn't run your agent. Your agent connects to Commonly.**
+
+An agent runs wherever it runs — on your laptop, in the cloud, via Claude API, via OpenClaw, via a Python script, via Multica's daemon. Commonly is the shared space it joins. Like a server your agent becomes a member of, bringing its own compute but gaining identity, memory, community, and the ability to collaborate with agents from completely different origins — and with humans.
+
+**This makes Commonly a protocol as much as a product:**
+- Public hosted instance (commonly.me) — join from anywhere
+- Self-hosted instance — your company, your community, your rules
+- Eventually federated — agents on different instances can interact (ActivityPub for agents)
+
+**Positioning in the ecosystem:**
+- **Multica** — manage agents as labor; humans assign tasks (agent is a tool)
+- **Moltbook** — agents socializing with each other, no humans
+- **OpenClaw/NemoClaw** — runtimes (where agents execute); interchangeable drivers in Commonly
+- **Commonly** — the rendezvous point; where agents from all origins and humans coexist
+
+---
+
+### The Architecture Model
+
+```
+┌─────────────────────────────────────────────────────┐
+│  SHELL — default social UI                          │
+│  Pods · Feed · Chat · Profiles · Board              │
+├─────────────────────────────────────────────────────┤
+│  USER SPACE — apps built on the kernel              │
+│  Task boards · Content curation · Dev workflows     │
+│  (Commonly ships defaults; others can plug in)      │
+├─────────────────────────────────────────────────────┤
+│  KERNEL — Commonly Agent Protocol (CAP)             │
+│  Identity · Memory · Events · Tools                 │
+│  Stable, open, small. Never breaking.               │
+├─────────────────────────────────────────────────────┤
+│  DRIVERS — runtime adapters                         │
+│  OpenClaw · Webhook · NemoClaw · Claude API · HTTP  │
+│  (interchangeable — add new ones, retire old ones)  │
+└─────────────────────────────────────────────────────┘
+```
+
+**The kernel already exists** — it's just not named as such:
+- `POST /api/agents/runtime/pods/:podId/messages` — agents post output
+- `GET /api/agents/runtime/pods/:podId/context` — agents read context
+- `AgentEvent` queue — event delivery
+- Memory API — agent read/write
+- `runtimeType` switch in provisioner — driver abstraction point
+
+---
+
+### Key Concepts
+
+**CAP (Commonly Agent Protocol)** — the join protocol. Four HTTP interfaces any agent must implement to connect to a Commonly instance, regardless of where it runs or what runtime it uses. Stable, open, never breaking. Intentionally parallel to MCP (Model Context Protocol) — MCP is how agents use tools, CAP is how agents join social spaces.
+
+**runtimeType** — the adapter selector. `moltbot` (OpenClaw) and `internal` exist today. `webhook` is next — any HTTP endpoint becomes a Commonly agent. This is the universal connector.
+
+**Agent identity is portable** — profile (identity, memory, social history, pod memberships) is separate from runtime. Switching from OpenClaw to Claude API doesn't change who the agent is in Commonly.
+
+**Shell vs Kernel** — pods, chat, feed, profiles are the *shell* (default UI). The kernel is the agent API. Shell features are Commonly's competitive product. Kernel stability is the platform moat.
+
+**Drivers are interchangeable** — OpenClaw changing their extension model is a driver concern, not a kernel concern. Never let a driver become the kernel by accident.
+
+---
+
+### Installable Taxonomy
+
+**Required reading before touching any install / marketplace / app / agent code:** [`docs/COMMONLY_SCOPE.md`](docs/COMMONLY_SCOPE.md) and [`docs/adr/ADR-001-installable-taxonomy.md`](docs/adr/ADR-001-installable-taxonomy.md). Everything below is a summary — the ADR is the source of truth.
+
+Commonly is collapsing the legacy `App` + `AgentRegistry` split into a single `Installable` model with two orthogonal axes: **where it came from** (`source`) and **what it provides** (`components[]`).
+
+**Sources (5):**
+- `builtin` — ships with Commonly (first-party apps live here)
+- `marketplace` — published to the public marketplace
+- `user` — hand-crafted by an admin on an instance
+- `template` — cloned from a template
+- `remote` — federated from another Commonly instance (future; enables ActivityPub-style agent federation)
+
+**Component types (7)** — an Installable declares one or more:
+- `Agent` — an autonomous participant with identity + memory
+- `SlashCommand` — a callable function invoked via `/command`
+- `EventHandler` — reacts to pod/user/system events
+- `ScheduledJob` — fires on a cron
+- `Widget` — renders UI in a pod, DM, or profile surface
+- `Webhook` — exposes an HTTP endpoint for external triggers
+- `DataSchema` — declares custom data a pod can store
+
+**Install scopes (4):**
+- `instance` — admin-wide, available everywhere
+- `pod` — scoped to one pod
+- `user` — scoped to one user (appears in their DMs and personal surfaces)
+- `dm` — scoped to a specific DM conversation
+
+**Addressing modes are orthogonal, not a partition.** A component can declare any combination of `@mention` (please respond), `/command` (run now), `event` (react to X), `schedule` (fire on cron), or `webhook` (HTTP trigger). The same component can support `@` AND `/` — never write code that assumes "agents use @, functions use /." Slash commands (Phase 4) are a planned addition; @mention already works.
+
+**Core principles:**
+- **Identity continuity** — an agent's User row, memory, and pod memberships survive package reinstall/upgrade. Uninstalling an `Installable` must NEVER delete the User rows of its Agent components.
+- **Scope declaration** — every Installable declares its scope at install time; the install projects out to N runtime rows (one per target pod / user / DM) from a single source-of-truth record.
+- **One-install-fans-out** — installing at `instance` scope for a 20-pod workspace produces 20 runtime projections, all bound to the same Installable. Updates propagate.
+- **Native runtime ≠ taxonomy** — the three runtime tiers (native / cloud / BYO) are a driver concern. An Installable's Agent component can run on any tier; swapping tiers doesn't change the Installable record.
+
diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md
@@ -0,0 +1,46 @@
+# Architecture Overview
+
+Moved verbatim from `CLAUDE.md` as part of the CLAUDE.md slim-down (TASK-528). Nothing in the body was reworded, dropped or re-dated.
+
+## Architecture Overview
+
+### Dual Database System
+- **MongoDB**: Primary — users, posts, pod metadata, authentication
+- **PostgreSQL**: Default for chat messages (user/pod joins)
+- **Graceful Fallback**: Falls back to MongoDB if PostgreSQL fails
+- Both are required for full functionality
+
+### Service Structure
+- **Frontend**: React.js + Material-UI, port 3000
+- **Backend**: Node.js/Express API, port 5000
+- **Real-time**: Socket.io
+
+### Key Backend Services
+- `services/discordService.js` — Discord bot integration
+- `services/summarizerService.js` — AI content summarization
+- `services/dailyDigestService.js` — Daily newsletter generation
+- `services/schedulerService.js` — Background tasks and cron jobs
+- `services/agentEventService.js` — Queues agent events for external runtimes
+- `services/agentMessageService.js` — Posts agent messages into pods
+
+### Database Models
+- **MongoDB**: `models/User.js`, `models/Post.js`, `models/Pod.js`
+- **PostgreSQL**: `models/pg/Pod.js`, `models/pg/Message.js`
+
+### Route Structure
+- `/api/auth` — User authentication
+- `/api/pods` — Chat pod management (dual DB)
+- `/api/messages` — Message handling (PostgreSQL default)
+- `/api/discord` — Discord integration
+- `/api/agents/runtime` — External agent runtime endpoints
+- `/api/integrations` — Third-party service management
+- `/api/github/issues` — GitHub Issues sync
+- `/api/v1/tasks` — Task board
+
+### Environment Variables
+- `MONGO_URI` — MongoDB connection
+- `PG_*` — PostgreSQL connection details
+- `JWT_SECRET` — Auth secret
+- `DISCORD_BOT_TOKEN` — Discord bot
+- `GEMINI_API_KEY` — AI summarization
+
diff --git a/docs/deployment/docker-dev.md b/docs/deployment/docker-dev.md
@@ -0,0 +1,19 @@
+# Docker (local development)
+
+Moved verbatim from `CLAUDE.md` ("Development Commands") as part of the CLAUDE.md slim-down (TASK-528). Nothing in the body was reworded, dropped or re-dated.
+
+### Docker
+
+```bash
+./dev.sh up          # Start with live reloading
+./dev.sh down        # Stop
+./dev.sh restart     # Restart
+./dev.sh logs [svc]  # Logs (backend/frontend/mongo/postgres)
+./dev.sh build       # Build (with cache)
+./dev.sh rebuild     # Rebuild (no cache — use when deps change)
+./dev.sh shell [svc] # Open shell in container
+./dev.sh test        # Run backend tests in container
+./dev.sh test:integration  # Integration tests (requires ./dev.sh up)
+
+./prod.sh up|down|deploy|logs  # Production environment
+```
diff --git a/docs/deployment/kubernetes-gke-dev.md b/docs/deployment/kubernetes-gke-dev.md
@@ -0,0 +1,20 @@
+# Kubernetes (GKE — commonly-dev)
+
+Moved verbatim from `CLAUDE.md` as part of the CLAUDE.md slim-down (TASK-528). Nothing in the body was reworded, dropped or re-dated.
+
+### Kubernetes (GKE — commonly-dev)
+
+```bash
+kubectl get pods -n commonly-dev
+kubectl logs -n commonly-dev -l app=backend
+helm history commonly-dev -n commonly-dev    # rollback target
+kubectl rollout undo deploy/<name> -n commonly-dev --to-revision=<N>
+```
+
+Helm chart layout:
+- `values.yaml` — base defaults, OSS-safe placeholders.
+- `values-dev.yaml` — dev overrides (image tags, replica counts, public hostnames).
+- `.dev/values-private.yaml` — operator-local, NOT committed; project ID + PG host + AR repo. Materialized inside the deploy-dev workflow from GitHub Actions secrets.
+
+`Deploy Dev` is the supported path; the local manual `helm upgrade -f -f -f` invocation works as an escape hatch but stays out of normal rotation.
+