mercury-agent 0.4.25 → 0.4.26

package/docs/ROADMAP.md

@@ -25,6 +25,8 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 | # | Item | Doc | Depends on | Why now |
 |---|------|-----|-----------|---------|
 | 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
+| 2 | **dm-auto-space** | [doc](backlog/dm-auto-space.md) | — | Auto-create space per customer DM |
+| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | — | Generic profile layer for business logic scoping |
 
 ## Later
 

package/docs/archive/2026-07-01-dm-auto-space.md

@@ -0,0 +1,273 @@
+# Auto-Create Space per DM
+
+**Status**: Done
+**Slug**: dm-auto-space
+**Created**: 2026-06-30
+**Last updated**: 2026-07-01
+
+---
+
+## Goal
+
+When Mercury serves a business (e.g. a barber shop), each customer texts from a unique phone number. Today every new DM creates a conversation with `space_id = null`, so the bot has no persistent per-customer context — it can't remember preferences, appointment history, or prior conversations. This feature adds a config-driven option to auto-create a space per customer and link their conversation to it, giving each customer an isolated, persistent context.
+
+## User Stories
+
+- As a business owner, I want each customer who messages my bot to automatically get their own space so the bot remembers their history across conversations.
+- As a business owner, I want my own number and staff numbers to auto-link to the `main` space instead of creating new spaces.
+- As a business owner, I want customers restricted to chat only — no tools, no scripts, no web search.
+- As a Mercury operator, I want this behavior off by default so existing deployments are unaffected.
+- As a Mercury operator, I want a global daily rate limit per role so I don't have to configure each space individually.
+
+## MVP Scope
+
+**In scope:**
+- New `dm_auto_space` config block in `mercury.yaml` with `enabled` (default `false`), `admin_numbers` (auto-link to `main`), `default_system_prompt`, and `default_member_permissions`
+- On new DM from a non-admin number: find or create a space for that phone number, **and link the conversation to it** (without linking, messages are silently dropped by the handler)
+- Admin numbers auto-link their DM conversation to `main` space
+- Auto-created spaces seeded with: `trigger.match = "always"`, `context.mode = "context"`, member permissions restricted to config value
+- Space `display_name` derived from the sender's push name (if available) or phone number
+- Returning customers hitting the same conversation get their existing space — no duplicate creation
+- New global daily rate limit defaults in `mercury.yaml` (`runtime.rate_limit_daily_member`, `runtime.rate_limit_daily_admin`) — applied as fallback when no per-space override exists
+- Dashboard UI: add rate limit controls to the space settings panel
+
+**Out of scope:**
+- Space merging when a customer contacts from multiple numbers — complex identity resolution, not MVP
+- Auto-space for group chats — DMs only for now
+- Per-bridge config (WhatsApp vs Telegram) — single global toggle for now, can be extended later
+
+---
+
+## Context for Claude
+
+> Key files to read before touching anything.
+
+- `src/config.ts` — Zod `schema` object (line 53) and `AppConfig` type; add new config fields here
+- `src/config-file.ts` — `mercuryFileSchema` (Zod for YAML parsing, line 25), `flattenMercuryFile()` (line 185), and `CAMEL_TO_ENV` (line 280); add the YAML blocks + env mappings here
+- `src/core/conversation.ts` — `resolveConversation()` (line 9) returns `null` when `space_id` is null; this is the hook point for auto-create + link
+- `src/core/handler.ts` — `createMessageHandler()` (line 17) calls `resolveConversation()` at line 50; needs to pass config + db context for auto-space logic
+- `src/storage/db.ts` — `ensureSpace()` (line 334), `linkConversation()` (line 611), `ensureConversation()` (line 471), `setSpaceConfig()`, `getSpaceConfig()`; space IDs must match `/^[a-z0-9][a-z0-9-]*$/`
+- `src/core/runtime.ts` — daily role-based rate limit check (line 397); burst rate limit fallback (line 424); needs fallback to new global daily rate limit config
+- `src/core/routes/dashboard.ts` — space settings panels (trigger, context); add rate limit panel here
+- `src/core/routes/config-builtin.ts` — `BUILTIN_CONFIG_KEYS` and `BUILTIN_CONFIG_DESCRIPTIONS`; add `rate_limit`, `rate_limit.member`, `rate_limit.admin` here so dashboard can manage them
+- `src/storage/memory.ts` — `ensureSpaceWorkspace()` (line 27) creates per-space dirs with empty `AGENTS.md`; already called lazily at container execution time (runtime.ts line 1142), no changes needed
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+No schema changes. Uses existing tables:
+
+- `spaces` — auto-created via `db.ensureSpace(spaceId)` with a derived slug
+- `conversations` — linked via `db.linkConversation(conversationId, spaceId)`
+- `space_config` — seeded with trigger, context, rate limit, permissions, and system prompt defaults on auto-created spaces
+
+**Space ID derivation:** Phone numbers (e.g. `972501234567@s.whatsapp.net`) must be converted to valid space IDs matching `/^[a-z0-9][a-z0-9-]*$/`. Strategy: strip the `@s.whatsapp.net` suffix and prefix with `dm-` → `dm-972501234567`. For other platforms: `dm-{platform}-{sanitized-external-id}`.
+
+**Space display name:** Use the sender's push name if available from the message, otherwise fall back to the phone number.
+
+### Config Shape
+
+```yaml
+# mercury.yaml
+
+# --- Part 1: Auto-space for DMs ---
+dm_auto_space:
+  enabled: false                              # default off
+  admin_numbers:                              # auto-link to "main" instead of creating a new space
+    - "972501234567"
+  default_system_prompt: "You are a barber shop assistant..."  # optional, seeded into space_config
+  default_member_permissions: "prompt,prefs.get"               # restrict customers to chat only
+
+# --- Part 2: Global daily rate limits (independent of dm_auto_space) ---
+runtime:
+  rate_limit_daily_member: 20                 # NEW — global default daily cap for members, 0 = unlimited
+  rate_limit_daily_admin: 0                   # NEW — global default daily cap for admins, 0 = unlimited
+```
+
+**Part 1 — dm_auto_space config keys:**
+- `dmAutoSpaceEnabled` → `MERCURY_DM_AUTO_SPACE_ENABLED` (boolean, default `false`)
+- `dmAutoSpaceAdminNumbers` → `MERCURY_DM_AUTO_SPACE_ADMIN_NUMBERS` (comma-separated string, default `""`)
+- `dmAutoSpaceDefaultSystemPrompt` → `MERCURY_DM_AUTO_SPACE_DEFAULT_SYSTEM_PROMPT` (string, default `""`)
+- `dmAutoSpaceDefaultMemberPermissions` → `MERCURY_DM_AUTO_SPACE_DEFAULT_MEMBER_PERMISSIONS` (string, default `"prompt,prefs.get"`)
+
+**Part 2 — global daily rate limit config keys:**
+- `rateLimitDailyMember` → `MERCURY_RATE_LIMIT_DAILY_MEMBER` (number, default `0` = unlimited)
+- `rateLimitDailyAdmin` → `MERCURY_RATE_LIMIT_DAILY_ADMIN` (number, default `0` = unlimited)
+
+### Space seeding on auto-create
+
+When a new customer space is created, the following `space_config` keys are seeded:
+
+| Key | Value | Why |
+|-----|-------|-----|
+| `trigger.match` | `"always"` | Bot responds to every message in DMs |
+| `context.mode` | `"context"` | Bot remembers conversation history |
+| `role.member.permissions` | from `default_member_permissions` config | Restrict customers to chat only |
+| `system_prompt` | from `default_system_prompt` config (if set) | Customer-facing persona |
+| `rate_limit.member` | from `rate_limit_daily_member` config (if >0) | Daily cap seeded from global default |
+
+### Global daily rate limit fallback
+
+In `runtime.ts` line 397, the daily role-based rate check currently reads `rate_limit.{role}` from `space_config` only. When the key is null (not set per-space), it currently skips the daily check entirely. Change: when the per-space key is null, fall back to the new global config value (`rateLimitDailyMember` / `rateLimitDailyAdmin`). A value of `0` means unlimited (skip check), which is the default — preserving backward compatibility.
+
+### API Contracts
+
+No new API endpoints. Auto-created spaces are fully managed through the existing space API (`/api/spaces`, `/api/conversations/:id/link`). Rate limits are managed via the existing `POST /dashboard/api/space-config` endpoint.
+
+### Dashboard: Rate limit panel
+
+Add a new "Rate Limits" section to the space settings page in `dashboard.ts`, following the same pattern as the Trigger and Context panels. Fields:
+
+| Label | Config key | Input | Notes |
+|-------|-----------|-------|-------|
+| Burst rate limit | `rate_limit` | number input | Per-user per-minute, falls back to global `rate_limit_per_user` |
+| Daily member limit | `rate_limit.member` | number input | Per-user per-day, falls back to global `rate_limit_daily_member` |
+| Daily admin limit | `rate_limit.admin` | number input | Per-user per-day, falls back to global `rate_limit_daily_admin` |
+
+Each row shows the effective value (per-space override or global default) and a "Reset" button to clear the override.
+
+Requires adding `rate_limit`, `rate_limit.member`, `rate_limit.admin` to `BUILTIN_CONFIG_KEYS`, `BUILTIN_CONFIG_DESCRIPTIONS`, and validators in `config-builtin.ts`.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/config-file.ts` | Modified | Add `dm_auto_space` and `runtime.rate_limit_daily_*` to YAML schema, flatten, env mappings |
+| `src/config.ts` | Modified | Add all new config fields to Zod schema |
+| `src/core/conversation.ts` | Modified | Add auto-space + admin-link logic in `resolveConversation()` |
+| `src/core/handler.ts` | Modified | Thread auto-space config into `resolveConversation()` call |
+| `src/core/runtime.ts` | Modified | Add global daily rate limit fallback in `handleRawInput()` |
+| `src/core/routes/dashboard.ts` | Modified | Add rate limit settings panel to space page |
+| `src/core/routes/config-builtin.ts` | Modified | Add rate limit keys to builtin config set |
+| `resources/templates/mercury.example.yaml` | Modified | Add commented dm_auto_space section and rate_limit_daily_* |
+| `tests/dm-auto-space.test.ts` | New | Unit tests for auto-space flow |
+| `tests/global-daily-rate-limit.test.ts` | New | Unit tests for global daily rate limit fallback |
+
+### Implementation Sequence
+
+1. **Add config fields** — Add `dm_auto_space` block and `runtime.rate_limit_daily_*` to `mercuryFileSchema` in `config-file.ts`, flatten in `flattenMercuryFile()`, add env mappings to `CAMEL_TO_ENV`, and add all new fields to the Zod schema in `config.ts`.
+   - Read first: `src/config-file.ts`, `src/config.ts`
+   - Verify: `bun run typecheck` passes
+
+2. **Add global daily rate limit fallback** — In `runtime.ts` `handleRawInput()`, when `rate_limit.{role}` is not set per-space, fall back to `config.rateLimitDailyMember` / `config.rateLimitDailyAdmin` instead of skipping.
+   - Read first: `src/core/runtime.ts` (lines 395-430)
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 1 (config fields must exist)
+
+3. **Add rate limit to dashboard + config-builtin** — Add `rate_limit`, `rate_limit.member`, `rate_limit.admin` to `BUILTIN_CONFIG_KEYS` and `BUILTIN_CONFIG_DESCRIPTIONS` in `config-builtin.ts`. Add a rate limit panel to the space page in `dashboard.ts` following the trigger/context panel pattern.
+   - Read first: `src/core/routes/config-builtin.ts`, `src/core/routes/dashboard.ts` (trigger panel ~line 250, context panel ~line 345)
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 1 (need global defaults to show "project default" label)
+
+4. **Implement auto-space logic in `resolveConversation()`** — When `conversation.spaceId` is null AND kind is `"dm"` AND config has `dmAutoSpaceEnabled: true`:
+   - If sender is in `admin_numbers`: link conversation to `"main"`, return resolution
+   - Otherwise: derive space ID (`dm-{sanitized-id}`), call `db.ensureSpace()`, seed `space_config` keys (trigger, context, permissions, system prompt, rate limit), call `db.linkConversation()`, return resolution
+   - Read first: `src/core/conversation.ts`, `src/core/handler.ts`, `src/storage/db.ts`
+   - Verify: `bun run typecheck` passes
+   - Blocker: Steps 1-2 (config fields and rate limit fallback must exist)
+
+5. **Thread config and author name through the call chain** — `resolveConversation()` currently takes `(db, platform, externalId, kind, observedTitle?)`. Add an `autoSpaceConfig` parameter with `{ enabled, adminNumbers, defaultSystemPrompt, defaultMemberPermissions, rateLimitDailyMember }` and an `authorName` parameter. The handler passes config from `config` and author name from `message.author.userName` (available before `resolveConversation` is called; set by WhatsApp adapter from `pushName`). Author name is used for the space display name.
+   - Read first: `src/core/handler.ts` (line 50 where resolveConversation is called), `src/adapters/whatsapp.ts` (line 497, 576 — `userName`/`fullName` set from pushName)
+   - Verify: `bun run typecheck` passes
+
+6. **Write tests** — Test the auto-space flow: enabled + non-admin → space created + linked + config seeded; admin number → linked to main; disabled → returns null; returning customer → reuses existing space. Test global daily rate limit fallback: per-space set → uses per-space; per-space not set → uses global; global is 0 → unlimited.
+   - Read first: existing test files in `tests/` for patterns
+   - Verify: `bun test` passes
+
+7. **Update example config** — Add commented `dm_auto_space` section and `rate_limit_daily_*` to `resources/templates/mercury.example.yaml`.
+   - Read first: `resources/templates/mercury.example.yaml`
+   - Verify: file contains the new sections
+
+---
+
+## Non-Negotiable Rules
+
+- **Default off** — `dm_auto_space.enabled` must default to `false`. Existing deployments must not change behavior.
+- **Admin numbers link to main** — admin numbers are auto-linked to the `main` space, never dropped. They never create a new space.
+- **Customer permissions are locked down** — auto-created spaces seed `role.member.permissions` from config (default `"prompt,prefs.get"`), stripping all extension tool access.
+- **Space ID format** — derived IDs must always pass the `/^[a-z0-9][a-z0-9-]*$/` regex. Strip all characters that don't match.
+- **No data loss** — auto-created spaces are regular spaces. Deleting them via the existing API unlinks conversations (FK ON DELETE SET NULL), which is the correct behavior.
+- **Idempotent** — `ensureSpace()` already does INSERT OR IGNORE. Space config seeding must use a read-before-write pattern (`getSpaceConfig` check before `setSpaceConfig`) because `setSpaceConfig` uses `ON CONFLICT DO UPDATE` which would overwrite manual overrides.
+- **Backward compatible rate limits** — global daily rate limit defaults to `0` (unlimited), preserving existing behavior for all deployments.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Same customer sends multiple messages before first one is processed | `ensureSpace()` is idempotent (INSERT OR IGNORE); `linkConversation()` is an UPDATE — safe for concurrent calls. Space config seeding uses read-before-write (`getSpaceConfig` → `setSpaceConfig` only if null), so first write wins and subsequent messages don't overwrite. |
+| Customer number produces an invalid space ID (starts with dash, etc.) | Sanitize: strip `@...` suffix, prefix with `dm-`, remove non-alphanumeric chars except hyphens |
+| Admin numbers in different formats (+972 vs 972 vs 972...@s.whatsapp.net) | Normalize: strip leading `+`, strip `@s.whatsapp.net` suffix before comparison |
+| Admin links a DM conversation to a different space manually | `resolveConversation()` only auto-creates when `spaceId` is null — if already linked, uses the existing link |
+| Feature is enabled then disabled | Existing auto-created spaces and links remain; new DMs from unknown numbers go back to being dropped |
+| Admin overrides rate limit per space via dashboard | Per-space value takes precedence over global default; "Reset" button clears override to fall back to global |
+| Very large number of unique customers | Each gets a space row + workspace dir + space_config entries. Acceptable for MVP; monitoring via `listSpaces()` count |
+| `main` space doesn't exist when admin number messages | `ensureSpace("main")` is called at runtime boot (runtime.ts line 88); always exists |
+| Race in space config seeding (read-before-write) | Two concurrent messages could both read null and both write. `setSpaceConfig` uses `ON CONFLICT DO UPDATE` so second write wins — acceptable since both write the same default values. The race only matters if an admin manually changed the config between the two messages, which is vanishingly unlikely during the first-message window. |
+| Push name not available (e.g., privacy settings) | Fall back to phone number as space display name. `message.author.userName` may be just the JID prefix — acceptable for MVP. |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal (fill before asking for approval)
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture (fill after Goal approved)
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (tick off as you go)
+- [x] Step 1 — Add config fields to `config-file.ts` and `config.ts`
+- [x] Step 2 — Add global daily rate limit fallback in `runtime.ts`
+- [x] Step 3 — Add rate limit to dashboard + config-builtin
+- [x] Step 4 — Implement auto-space logic in `resolveConversation()`
+- [x] Step 5 — Thread config through handler → resolveConversation call chain
+- [x] Step 6 — Write tests
+- [x] Step 7 — Update example config
+- [x] `bun run check` passes
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+- [x] All user stories verifiably met
+
+---
+
+## Open Questions
+
+- [x] Config key naming — confirmed: `dm_auto_space: { enabled, admin_numbers, default_system_prompt, default_member_permissions }`
+- [x] Should `exclude` match exact numbers or support patterns/wildcards? — exact phone numbers only
+- [x] What happens to excluded/admin numbers? — auto-linked to `main`, not dropped
+- [x] How to restrict customer tools? — seed `role.member.permissions` via `default_member_permissions` config
+- [x] How to set trigger mode? — auto-seeded `trigger.match = "always"` on customer spaces
+- [x] Global daily rate limits? — added to `runtime` config block, per-space dashboard override on top
+
+---
+
+## Retrospective
+
+> Fill this section when archiving.
+
+**Residual risks / follow-ups:**
+- Per-space AGENTS.md for auto-created spaces is empty by default; the global AGENTS.md applies but a dedicated customer-facing template could improve quality — accepted
+- Business logic (appointment booking, etc.) must be handled by dedicated business extensions with deterministic code, NOT via LLM prompting → ideas/business-extensions.md
+
+**What changed from the plan:**
+- Steps 4 and 5 (auto-space logic + config threading) implemented together as they are tightly coupled
+- Added `.toLowerCase()` to `deriveSpaceId` for future non-numeric platform IDs (caught in code review)
+- `memory.ts` removed from modified files list — `ensureSpaceWorkspace` is already called lazily at container execution time
+
+**Key decisions made during implementation:**
+- Used `seedSpaceConfigIfAbsent` helper (read-before-write) instead of raw `setSpaceConfig` to avoid overwriting manual admin overrides
+- Author name sourced from `message.author.userName` (set from WhatsApp pushName) before `resolveConversation` — available before bridge normalization
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] New package/module added
+- [ ] New data model or schema change
+- [ ] New inter-package interaction
+- [ ] Deployment topology changed

package/docs/backlog/applicative-profiles.md

@@ -0,0 +1,273 @@
+# Applicative Profiles
+
+**Status**: Backlog
+**Slug**: applicative-profiles
+**Created**: 2026-07-01
+**Last updated**: 2026-07-01
+
+---
+
+## Goal
+
+Mercury's existing profile system (`src/core/profiles.ts`) is a static provisioning mechanism — it bundles extensions, AGENTS.md, env vars, and config defaults into a deployable template. But it has no runtime behavior: it can't scope which capabilities members access, enforce data isolation (ownership), or declare capability dependencies. Business workflows (appointment booking, customer management) require deterministic logic that can't be reliably delegated to the LLM.
+
+Applicative Profiles extend the existing profile system with a **runtime contract** — a profile declares what capabilities it wraps, what commands it exposes to members, and what isolation rules it enforces. Mercury provides the schema, loader, and runtime enforcement; profiles live in external repos. The barber-appointments profile is the first implementation to validate the design.
+
+## User Stories
+
+- As a Mercury operator, I want to install a profile package from an external repo so my bot gains domain-specific business logic without modifying Mercury core.
+- As a barber shop owner, I want my customers (DM members) to book and cancel only their own appointments through the bot, without seeing other customers' schedules.
+- As a barber shop owner, I want my customers to have zero access to my Gmail, even though the profile uses my GWS credentials for calendar access internally.
+- As a profile developer, I want a clear schema/contract for defining profiles so I know what to implement (commands, permissions, capability dependencies, data isolation rules).
+- As a Mercury admin, I want raw capability extensions (GWS, web search) to remain admin-only while the profile's scoped commands are member-facing.
+
+## MVP Scope
+
+**In scope:**
+- Extend `mercury-profile.yaml` schema with runtime fields: `capabilities` (required extensions), `member_permissions` (exhaustive permission list for members), and `system_prompt` (profile-specific agent persona)
+- Profile-aware permission resolution — when a profile is active, member permissions come from the profile, not from extension defaults
+- Capability dependency validation — profile apply fails if required extensions aren't installed
+- Profile activation per space — a space can have an active profile that governs its runtime behavior
+- `CALLER_ID` injection — profile extensions receive the caller's identity so they can enforce ownership in their CLI code
+- Barber-appointments profile (separate repo) as the first implementation to validate the design
+
+**Out of scope (deferred):**
+- Profile marketplace/registry — profiles are installed manually (npm/bun add or git clone) for now
+- Profile versioning/migration — no schema version negotiation yet
+- Multi-profile per space — one profile per space for MVP
+- Profile UI in dashboard — managed via config/YAML only
+- Declarative data isolation rules — ownership enforcement is in profile extension code, not a schema declaration (too domain-specific for a generic schema in v1)
+
+---
+
+## Context for Claude
+
+> Key files to read before touching anything.
+
+- `src/core/profiles.ts` — Existing profile system: `profileSchema`, `loadProfileFromDir()`, `applyProfile()`, `resolveProfileSource()`. Bundles extensions + AGENTS.md + env + defaults into `.mercury/`
+- `src/extensions/types.ts` — Extension type system: `MercuryExtensionAPI`, `ExtensionMeta`, `PermissionDef`, `CliDef`, `EnvDef`. The API surface extensions use during setup
+- `src/core/permissions.ts` — Permission resolution: `getRolePermissions()`, `registerPermission()`, `resolveRole()`. Role-based (admin/member) per space with extension-registered defaults
+- `src/extensions/permission-guard.ts` — Container-side enforcement: reads `MERCURY_DENIED_CLIS` env var and blocks unauthorized CLI calls
+- `src/extensions/loader.ts` — `ExtensionRegistry` class: scans `.mercury/extensions/`, validates, runs setup functions, collects `ExtensionMeta`
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+Extend the existing `profileSchema` in `src/core/profiles.ts`:
+
+```typescript
+// New fields added to profileSchema
+const profileSchema = z.object({
+  // ... existing fields ...
+  name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+  description: z.string().optional(),
+  version: z.string().default("0.1.0"),
+  agents_md: z.string().optional(),
+  extensions: z.array(profileExtensionSchema).default([]),
+  env: z.array(profileEnvVarSchema).default([]),
+  defaults: profileDefaultsSchema.optional(),
+
+  // NEW — runtime applicative fields
+  capabilities: z.array(z.string()).default([]),          // required raw extensions (e.g. ["gws"])
+  member_permissions: z.array(z.string()).optional(),     // exhaustive member permission list when profile is active
+  system_prompt: z.string().optional(),                   // profile-specific agent persona
+});
+```
+
+New DB storage — per-space active profile tracking via existing `space_config`:
+- Key: `profile.active` — value: profile name (e.g. `"barber-appointments"`)
+- Key: `profile.member_permissions` — value: comma-separated permission list from the profile manifest
+
+No new tables or migrations needed.
+
+### How it works at runtime
+
+1. **Profile apply** (`applyProfile()` extended): copies extensions + AGENTS.md (existing behavior), then validates that all `capabilities` are installed as extensions, and stores the profile's `member_permissions` in a resolvable location.
+
+2. **Permission resolution** (`getRolePermissions()` extended): when a space has `profile.active` set, member permissions come from `profile.member_permissions` instead of the default `prompt + prefs.get + extension defaults`. Admin permissions are unchanged (all). This means raw capabilities (e.g., `gws`) stay admin-only unless the profile explicitly lists them in `member_permissions`.
+
+3. **Capability scoping**: the profile's own extensions call `mercury.permission({ defaultRoles: ["member"] })` to make their commands member-accessible. Raw capability extensions (e.g., `gws`) are NOT in `member_permissions`, so their CLIs are denied by `permission-guard.ts`. The profile extension uses the raw capability internally (server-side hooks, or by passing credentials via env vars that only the extension code — not the container — can access).
+
+4. **Data isolation / ownership**: handled in the profile extension's CLI code. The container already receives `CALLER_ID` (the platform user ID). The profile's CLI checks the caller against the data before acting (e.g., "does this appointment belong to this caller?"). This is intentionally not a generic schema — it's too domain-specific.
+
+5. **Gmail protection**: the `gws` extension exposes both Calendar and Gmail CLIs. When the barber profile is active, `member_permissions` does NOT include `gws`, so the permission guard blocks all `gws` CLI calls for members. The barber extension accesses Calendar server-side (via hooks or its own env vars) — members never touch GWS directly.
+
+### Example: barber-appointments profile
+
+```yaml
+# mercury-profile.yaml (in separate repo)
+name: barber-appointments
+description: Appointment booking for a barber shop
+version: 0.1.0
+
+agents_md: ./AGENTS.md
+
+capabilities:
+  - gws                    # requires GWS extension installed (for Calendar)
+
+extensions:
+  - name: barber
+    source: ./extensions/barber
+
+member_permissions:
+  - prompt
+  - prefs.get
+  - barber                 # only the barber extension — NOT gws
+
+env:
+  - key: MERCURY_BARBER_BUSINESS_HOURS
+    description: "Business hours (e.g. 09:00-18:00)"
+    default: "09:00-18:00"
+  - key: MERCURY_BARBER_SLOT_DURATION
+    description: "Appointment slot duration in minutes"
+    default: "30"
+
+system_prompt: |
+  You are a barber shop assistant. Help customers book, view, and cancel
+  their appointments. You can only help each customer with their own
+  appointments — never reveal other customers' schedules.
+
+defaults:
+  trigger_patterns: "always"
+```
+
+The barber extension (`./extensions/barber/index.ts`):
+- Calls `mercury.cli({ name: "barber", ... })` — installs a CLI with subcommands: `barber book`, `barber availability`, `barber cancel`, `barber my-appointments`
+- Calls `mercury.permission({ defaultRoles: ["member"] })` — members can use the `barber` CLI
+- The CLI internally uses GWS Calendar API (via env var credentials) but filters results by `CALLER_ID`
+- Members NEVER see the `gws` CLI — it's blocked by the permission guard
+
+### API Contracts
+
+No new HTTP API endpoints. Profile activation is done via:
+1. `mercury.yaml` — `profile: barber-appointments` (static config)
+2. `space_config` — `profile.active: barber-appointments` (per-space override)
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `src/core/profiles.ts` | Modified | Extend `profileSchema` with `capabilities`, `member_permissions`, `system_prompt`. Add validation in `applyProfile()` |
+| `src/core/permissions.ts` | Modified | Profile-aware `getRolePermissions()` — check `profile.member_permissions` for the space |
+| `src/config.ts` | Modified | Add `profile` config key for static profile activation |
+| `src/config-file.ts` | Modified | Add `profile` to YAML schema and env mapping |
+| `tests/applicative-profiles.test.ts` | New | Tests for profile permission scoping and capability validation |
+
+### Implementation Sequence
+
+1. **Extend profile schema** — Add `capabilities`, `member_permissions`, `system_prompt` to `profileSchema` in `profiles.ts`. These are optional fields so existing profiles remain valid.
+   - Read first: `src/core/profiles.ts`
+   - Verify: `bun run typecheck` passes
+
+2. **Add capability validation** — In `applyProfile()`, after copying extensions, check that every entry in `capabilities` has a matching directory in `.mercury/extensions/`. Throw a clear error if a required capability is missing.
+   - Read first: `src/core/profiles.ts`, `src/extensions/loader.ts`
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 1
+
+3. **Store profile activation in space_config** — When `applyProfile()` runs for a space, write `profile.active` and `profile.member_permissions` to `space_config`. Add `profile` config key to `config.ts` / `config-file.ts` for static activation.
+   - Read first: `src/config.ts`, `src/config-file.ts`, `src/storage/db.ts`
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 1
+
+4. **Profile-aware permission resolution** — In `getRolePermissions()`, when the space has `profile.member_permissions` set, use that as the member permission set instead of the default. Admin/system roles unchanged.
+   - Read first: `src/core/permissions.ts`
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 3
+
+5. **System prompt injection** — When a profile has `system_prompt`, inject it via the existing `before_container` hook mechanism or config seeding (same pattern as `dm-auto-space`'s `default_system_prompt`).
+   - Read first: `src/core/runtime.ts`, `src/extensions/hooks.ts`
+   - Verify: `bun run typecheck` passes
+   - Blocker: Step 3
+
+6. **Write tests** — Profile permission scoping: member gets only profile-declared permissions; admin gets all; raw capability blocked for members. Capability validation: apply fails when required extension missing. Profile activation: space_config correctly set.
+   - Read first: `tests/permissions.test.ts`
+   - Verify: `bun test` passes
+   - Blocker: Steps 1-5
+
+7. **Update example config** — Add commented `profile` section to `mercury.example.yaml`.
+   - Read first: `resources/templates/mercury.example.yaml`
+   - Verify: file contains the new section
+
+---
+
+## Non-Negotiable Rules
+
+- **Profiles are external** — Mercury core provides the schema, loader, and runtime. No specific profile (barber, etc.) lives in this repo.
+- **Member permissions are exhaustive** — When a profile declares `member_permissions`, that is the COMPLETE set. No extension defaults are merged in. This prevents capability leakage.
+- **Admin permissions unchanged** — Admins always get all permissions regardless of profile. Profiles scope members only.
+- **Capability validation is strict** — `applyProfile()` must fail loudly if a required capability extension is not installed. Silent degradation is not acceptable.
+- **Data isolation is code, not config** — Ownership enforcement happens in the profile extension's CLI code, not in a declarative schema. The extension checks `CALLER_ID` before acting.
+- **Backward compatible** — Existing profiles without the new fields continue to work exactly as before. All new fields are optional.
+- **No Gmail exposure** — When a profile wraps GWS for Calendar access, the raw `gws` CLI (which includes Gmail) must be blocked for members via permission scoping.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Profile declares `member_permissions: ["nonexistent"]` | `isValidPermission()` filters invalid names. Log a warning but don't crash — the invalid permission is silently dropped. |
+| Profile requires capability `gws` but it's not installed | `applyProfile()` throws with a clear error listing missing capabilities. |
+| Admin manually overrides `role.member.permissions` per space | Per-space override in `space_config` takes precedence over profile defaults (existing behavior). Profile sets the baseline; admin can further restrict or expand. |
+| Profile is removed/changed but space_config still references it | `profile.active` becomes stale. Permission resolution still works from the stored `profile.member_permissions`. On next `applyProfile()` the values are updated. |
+| Two extensions declare the same CLI name | Existing loader behavior: second registration throws. No change needed. |
+| Profile extension tries to call raw capability CLI in container | Allowed only if the extension is running as admin (hooks run on host, not in container). Container CLI calls go through permission guard. |
+| Caller ID not available (e.g., system-triggered task) | `CALLER_ID` is already `"system"` for scheduled tasks. Profile extension should handle this gracefully (e.g., skip ownership check for system callers). |
+| Existing deployment upgrades Mercury with profiles feature | No behavioral change. `member_permissions` is optional; when absent, existing permission resolution applies. |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal (fill before asking for approval)
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture (fill after Goal approved)
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (tick off as you go)
+- [ ] Step 1 — Extend profile schema
+- [ ] Step 2 — Add capability validation
+- [ ] Step 3 — Store profile activation in space_config
+- [ ] Step 4 — Profile-aware permission resolution
+- [ ] Step 5 — System prompt injection
+- [ ] Step 6 — Write tests
+- [ ] Step 7 — Update example config
+- [ ] `bun run check` passes
+- [ ] No secrets or `.env` files committed
+- [ ] No unrelated files modified
+- [ ] All user stories verifiably met
+
+---
+
+## Open Questions
+
+- [ ] Should `dm_auto_space` auto-activate a profile for new customer spaces? (Likely yes — `dm_auto_space.profile: barber-appointments` config key) — owner: TBD
+- [ ] How does `CALLER_ID` map to appointment ownership? Phone number? Display name? A registration step? — owner: profile developer (barber repo)
+
+---
+
+## Retrospective
+
+> Fill this section when archiving.
+
+**Residual risks / follow-ups:**
+- none
+
+**What changed from the plan:**
+- ...
+
+**Key decisions made during implementation:**
+- ...
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [ ] New package/module added
+- [ ] New data model or schema change
+- [ ] New inter-package interaction
+- [ ] Deployment topology changed

package/docs/pending-updates/dm-auto-space.md

@@ -0,0 +1,15 @@
+---
+slug: dm-auto-space
+shipped: 2026-07-01
+---
+
+## ROADMAP changes
+
+**Remove from:** Next (table row where Item = dm-auto-space)
+
+**Also pull:** none
+
+**Add to Shipped table** (insert at top, after header row):
+| **dm-auto-space** | 2026-07-01 | Auto-create space per customer DM with rate limits and dashboard controls |
+
+**Milestone Map:** none

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/resources/templates/mercury.example.yaml

@@ -40,6 +40,8 @@
 #   log_format: text
 #   rate_limit_per_user: 10
 #   rate_limit_window_ms: 60000
+#   rate_limit_daily_member: 0     # 0 = unlimited; global daily message cap for members
+#   rate_limit_daily_admin: 0      # 0 = unlimited; global daily message cap for admins
 
 # trigger:
 #   patterns: "@Mercury,Mercury"
@@ -73,3 +75,10 @@
 
 # permissions:
 #   admins: ""
+
+# dm_auto_space:
+#   enabled: false
+#   admin_numbers:                              # auto-link to "main" space
+#     - "972501234567"
+#   default_system_prompt: ""                   # seeded into auto-created customer spaces
+#   default_member_permissions: "prompt,prefs.get"  # restrict customers to chat only

package/src/config-file.ts

@@ -85,6 +85,8 @@ const mercuryFileSchema = z
           .min(1000)
           .max(60 * 60 * 1000)
           .optional(),
+        rate_limit_daily_member: z.number().int().min(0).max(10000).optional(),
+        rate_limit_daily_admin: z.number().int().min(0).max(10000).optional(),
       })
       .strict()
       .optional(),
@@ -161,6 +163,16 @@ const mercuryFileSchema = z
       })
       .strict()
       .optional(),
+
+    dm_auto_space: z
+      .object({
+        enabled: z.boolean().optional(),
+        admin_numbers: z.array(z.string()).optional(),
+        default_system_prompt: z.string().optional(),
+        default_member_permissions: z.string().optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict();
 
@@ -233,6 +245,12 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
   if (f.runtime?.rate_limit_window_ms != null) {
     o.rateLimitWindowMs = f.runtime.rate_limit_window_ms;
   }
+  if (f.runtime?.rate_limit_daily_member != null) {
+    o.rateLimitDailyMember = f.runtime.rate_limit_daily_member;
+  }
+  if (f.runtime?.rate_limit_daily_admin != null) {
+    o.rateLimitDailyAdmin = f.runtime.rate_limit_daily_admin;
+  }
 
   if (f.scheduling?.default_timezone != null) {
     o.defaultTimezone = f.scheduling.default_timezone;
@@ -273,6 +291,20 @@ function flattenMercuryFile(f: MercuryFile): RawMercuryConfigInput {
 
   if (f.permissions?.admins != null) o.admins = f.permissions.admins;
 
+  if (f.dm_auto_space?.enabled != null) {
+    o.dmAutoSpaceEnabled = f.dm_auto_space.enabled;
+  }
+  if (f.dm_auto_space?.admin_numbers != null) {
+    o.dmAutoSpaceAdminNumbers = f.dm_auto_space.admin_numbers.join(",");
+  }
+  if (f.dm_auto_space?.default_system_prompt != null) {
+    o.dmAutoSpaceDefaultSystemPrompt = f.dm_auto_space.default_system_prompt;
+  }
+  if (f.dm_auto_space?.default_member_permissions != null) {
+    o.dmAutoSpaceDefaultMemberPermissions =
+      f.dm_auto_space.default_member_permissions;
+  }
+
   return o;
 }
 
@@ -335,6 +367,13 @@ const CAMEL_TO_ENV: Record<string, string> = {
   googleApplicationCredentials: "MERCURY_GOOGLE_APPLICATION_CREDENTIALS",
   ttsMaxChars: "MERCURY_TTS_MAX_CHARS",
   defaultTimezone: "MERCURY_DEFAULT_TIMEZONE",
+  rateLimitDailyMember: "MERCURY_RATE_LIMIT_DAILY_MEMBER",
+  rateLimitDailyAdmin: "MERCURY_RATE_LIMIT_DAILY_ADMIN",
+  dmAutoSpaceEnabled: "MERCURY_DM_AUTO_SPACE_ENABLED",
+  dmAutoSpaceAdminNumbers: "MERCURY_DM_AUTO_SPACE_ADMIN_NUMBERS",
+  dmAutoSpaceDefaultSystemPrompt: "MERCURY_DM_AUTO_SPACE_DEFAULT_SYSTEM_PROMPT",
+  dmAutoSpaceDefaultMemberPermissions:
+    "MERCURY_DM_AUTO_SPACE_DEFAULT_MEMBER_PERMISSIONS",
 };
 
 function envValueForSchema(

package/src/config.ts

@@ -169,6 +169,8 @@ const schema = z.object({
     .min(1000)
     .max(60 * 60 * 1000)
     .default(60 * 1000), // 1 minute
+  rateLimitDailyMember: z.coerce.number().int().min(0).max(10000).default(0),
+  rateLimitDailyAdmin: z.coerce.number().int().min(0).max(10000).default(0),
 
   // ─── Server ─────────────────────────────────────────────────────────
   port: z.coerce.number().int().min(1).max(65535).default(8787),
@@ -247,6 +249,12 @@ const schema = z.object({
   googleApplicationCredentials: z.string().optional(),
   /** Max input characters per /api/tts request (clamped 500–10000). */
   ttsMaxChars: z.coerce.number().int().min(500).max(10_000).default(5000),
+
+  // ─── DM Auto-Space ─────────────────────────────────────────────────
+  dmAutoSpaceEnabled: booleanFromEnv.default(false),
+  dmAutoSpaceAdminNumbers: z.string().default(""),
+  dmAutoSpaceDefaultSystemPrompt: z.string().default(""),
+  dmAutoSpaceDefaultMemberPermissions: z.string().default("prompt,prefs.get"),
 });
 
 export type AppConfig = z.infer<typeof schema> & {

package/src/core/conversation.ts

@@ -1,3 +1,4 @@
+import { logger } from "../logger.js";
 import type { Db } from "../storage/db.js";
 import type { Conversation } from "../types.js";
 
@@ -6,12 +7,45 @@ export interface ConversationResolution {
   spaceId: string;
 }
 
+export interface AutoSpaceConfig {
+  enabled: boolean;
+  adminNumbers: string[];
+  defaultSystemPrompt: string;
+  defaultMemberPermissions: string;
+  rateLimitDailyMember: number;
+}
+
+function normalizePhone(raw: string): string {
+  return raw.replace(/^[+]+/, "").replace(/@.*$/, "");
+}
+
+function deriveSpaceId(platform: string, externalId: string): string {
+  const cleaned = normalizePhone(externalId)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "");
+  if (platform === "whatsapp") return `dm-${cleaned}`;
+  return `dm-${platform}-${cleaned}`;
+}
+
+function seedSpaceConfigIfAbsent(
+  db: Db,
+  spaceId: string,
+  key: string,
+  value: string,
+): void {
+  if (db.getSpaceConfig(spaceId, key) === null) {
+    db.setSpaceConfig(spaceId, key, value, "dm-auto-space");
+  }
+}
+
 export function resolveConversation(
   db: Db,
   platform: string,
   externalId: string,
   kind: string,
   observedTitle?: string,
+  autoSpace?: AutoSpaceConfig,
+  authorName?: string,
 ): ConversationResolution | null {
   const conversation = db.ensureConversation(
     platform,
@@ -20,9 +54,71 @@ export function resolveConversation(
     observedTitle,
   );
 
-  if (!conversation.spaceId) return null;
+  if (conversation.spaceId) {
+    return { conversation, spaceId: conversation.spaceId };
+  }
+
+  if (!autoSpace?.enabled || kind !== "dm") return null;
 
-  return { conversation, spaceId: conversation.spaceId };
+  const senderNormalized = normalizePhone(externalId);
+  const isAdmin = autoSpace.adminNumbers.some(
+    (n) => normalizePhone(n) === senderNormalized,
+  );
+
+  if (isAdmin) {
+    db.ensureSpace("main");
+    db.linkConversation(conversation.id, "main");
+    logger.info("dm-auto-space: admin number linked to main", {
+      platform,
+      externalId: senderNormalized,
+    });
+    return {
+      conversation: { ...conversation, spaceId: "main" },
+      spaceId: "main",
+    };
+  }
+
+  const spaceId = deriveSpaceId(platform, externalId);
+  db.ensureSpace(spaceId);
+
+  const displayName = authorName || senderNormalized;
+  db.updateSpaceName(spaceId, displayName);
+
+  seedSpaceConfigIfAbsent(db, spaceId, "trigger.match", "always");
+  seedSpaceConfigIfAbsent(db, spaceId, "context.mode", "context");
+  if (autoSpace.defaultMemberPermissions) {
+    seedSpaceConfigIfAbsent(
+      db,
+      spaceId,
+      "role.member.permissions",
+      autoSpace.defaultMemberPermissions,
+    );
+  }
+  if (autoSpace.defaultSystemPrompt) {
+    seedSpaceConfigIfAbsent(
+      db,
+      spaceId,
+      "system_prompt",
+      autoSpace.defaultSystemPrompt,
+    );
+  }
+  if (autoSpace.rateLimitDailyMember > 0) {
+    seedSpaceConfigIfAbsent(
+      db,
+      spaceId,
+      "rate_limit.member",
+      String(autoSpace.rateLimitDailyMember),
+    );
+  }
+
+  db.linkConversation(conversation.id, spaceId);
+  logger.info("dm-auto-space: created space and linked conversation", {
+    platform,
+    externalId: senderNormalized,
+    spaceId,
+    displayName,
+  });
+  return { conversation: { ...conversation, spaceId }, spaceId };
 }
 
 export function inferConversationKind(

package/src/core/handler.ts

@@ -3,7 +3,11 @@ import { telegramInboundLooksLikeMedia } from "../bridges/telegram.js";
 import type { AppConfig } from "../config.js";
 import { logger } from "../logger.js";
 import type { NormalizeContext, PlatformBridge } from "../types.js";
-import { inferConversationKind, resolveConversation } from "./conversation.js";
+import {
+  type AutoSpaceConfig,
+  inferConversationKind,
+  resolveConversation,
+} from "./conversation.js";
 import type { MercuryCoreRuntime } from "./runtime.js";
 import { loadTriggerConfig, matchTrigger } from "./trigger.js";
 
@@ -21,6 +25,19 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
     .map((s: string) => s.trim())
     .filter(Boolean);
 
+  const autoSpaceConfig: AutoSpaceConfig | undefined = config.dmAutoSpaceEnabled
+    ? {
+        enabled: true,
+        adminNumbers: config.dmAutoSpaceAdminNumbers
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+        defaultSystemPrompt: config.dmAutoSpaceDefaultSystemPrompt,
+        defaultMemberPermissions: config.dmAutoSpaceDefaultMemberPermissions,
+        rateLimitDailyMember: config.rateLimitDailyMember,
+      }
+    : undefined;
+
   return async (
     adapter: Adapter,
     threadId: string,
@@ -52,6 +69,9 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
         bridge.platform,
         externalId,
         kind,
+        undefined,
+        autoSpaceConfig,
+        message.author.userName ?? message.author.fullName,
       );
 
       if (!resolution) {

package/src/core/routes/config-builtin.ts

@@ -10,6 +10,9 @@ export const BUILTIN_CONFIG_KEYS = new Set([
   "context.window_size",
   "context.reply_chain_depth",
   "security.sensitive_connections_allowed",
+  "rate_limit",
+  "rate_limit.member",
+  "rate_limit.admin",
 ]);
 
 /**
@@ -37,6 +40,12 @@ export const BUILTIN_CONFIG_DESCRIPTIONS: Record<string, string> = {
     "Max number of turns walked back when following a reply chain. Integer 1-50.",
   "security.sensitive_connections_allowed":
     "When true, sensitive integrations (e.g. payments, identity) are usable in this group space. False blocks them by default.",
+  rate_limit:
+    "Per-user burst rate limit (messages per window). Overrides global rate_limit_per_user for this space. Integer ≥ 1, or 0 for unlimited.",
+  "rate_limit.member":
+    "Daily message cap for members in this space. Overrides global rate_limit_daily_member. Integer ≥ 1, or 0 for unlimited.",
+  "rate_limit.admin":
+    "Daily message cap for admins in this space. Overrides global rate_limit_daily_admin. Integer ≥ 1, or 0 for unlimited.",
 };
 
 const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
@@ -76,6 +85,24 @@ const BUILTIN_VALIDATORS: Record<string, (v: string) => string | null> = {
     ["true", "false"].includes(v)
       ? null
       : "Invalid security.sensitive_connections_allowed value. Valid: true, false",
+  rate_limit: (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 0 && n <= 1000
+      ? null
+      : "Invalid rate_limit value. Must be an integer between 0 and 1000";
+  },
+  "rate_limit.member": (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 0 && n <= 10000
+      ? null
+      : "Invalid rate_limit.member value. Must be an integer between 0 and 10000";
+  },
+  "rate_limit.admin": (v) => {
+    const n = Number.parseInt(v, 10);
+    return Number.isInteger(n) && n >= 0 && n <= 10000
+      ? null
+      : "Invalid rate_limit.admin value. Must be an integer between 0 and 10000";
+  },
 };
 
 export function isBuiltinConfigKey(key: string): boolean {

package/src/core/routes/dashboard.ts

@@ -423,6 +423,71 @@ export function createDashboardRoutes(ctx: DashboardContext) {
     `;
   }
 
+  function renderRateLimitPanel(
+    spaceId: string,
+    spacePageReload: string,
+  ): string {
+    const cfg = core.config;
+    const burstRaw = core.db.getSpaceConfig(spaceId, "rate_limit");
+    const memberRaw = core.db.getSpaceConfig(spaceId, "rate_limit.member");
+    const adminRaw = core.db.getSpaceConfig(spaceId, "rate_limit.admin");
+
+    const effectiveBurst = burstRaw ?? String(cfg.rateLimitPerUser);
+    const effectiveMember =
+      memberRaw ??
+      (cfg.rateLimitDailyMember > 0 ? String(cfg.rateLimitDailyMember) : "0");
+    const effectiveAdmin =
+      adminRaw ??
+      (cfg.rateLimitDailyAdmin > 0 ? String(cfg.rateLimitDailyAdmin) : "0");
+
+    const hasOverride = (key: string) =>
+      core.db.getSpaceConfig(spaceId, key) !== null;
+
+    const resetBtn = (key: string) =>
+      hasOverride(key)
+        ? `<button type="button" class="btn btn-sm" title="Use project default"
+             hx-delete="/dashboard/api/space-config?spaceId=${encodeURIComponent(spaceId)}&key=${encodeURIComponent(key)}"
+             hx-swap="none"
+             hx-on::after-request="${spacePageReload}">Reset</button>`
+        : "";
+
+    const sid = escapeHtml(spaceId);
+
+    const numRow = (label: string, key: string, value: string) => {
+      const desc = BUILTIN_CONFIG_DESCRIPTIONS[key];
+      const titleAttr = desc ? ` title="${escapeHtml(desc)}"` : "";
+      return `<div class="role-row" style="flex-wrap:wrap;align-items:center;gap:8px;margin-bottom:10px">
+      <span style="min-width:160px;font-weight:500"${titleAttr}>${escapeHtml(label)}</span>
+      <form style="display:flex;gap:8px;align-items:center;flex:1;flex-wrap:wrap" class="trigger-cfg-form"
+            hx-post="/dashboard/api/space-config" hx-swap="none" hx-on::after-request="${spacePageReload}">
+        <input type="hidden" name="spaceId" value="${sid}" />
+        <input type="hidden" name="key" value="${escapeHtml(key)}" />
+        <input type="number" name="value" class="select" value="${escapeHtml(value)}" min="0" required style="width:80px" />
+        <button type="submit" class="btn btn-sm">Save</button>
+      </form>
+      ${resetBtn(key)}
+    </div>`;
+    };
+
+    return `
+      <p class="muted" style="margin-bottom:10px;line-height:1.5">
+        <strong>Project default</strong> (from env / mercury.yaml):
+        burst <span class="mono">${cfg.rateLimitPerUser}/min</span>,
+        daily member <span class="mono">${cfg.rateLimitDailyMember === 0 ? "unlimited" : String(cfg.rateLimitDailyMember)}</span>,
+        daily admin <span class="mono">${cfg.rateLimitDailyAdmin === 0 ? "unlimited" : String(cfg.rateLimitDailyAdmin)}</span>.
+      </p>
+      <p class="muted" style="margin-bottom:16px;line-height:1.5;font-size:0.92em">
+        <strong>Effective</strong> for this space:
+        burst <span class="mono">${escapeHtml(effectiveBurst)}/min</span>,
+        daily member <span class="mono">${effectiveMember === "0" ? "unlimited" : escapeHtml(effectiveMember)}/day</span>,
+        daily admin <span class="mono">${effectiveAdmin === "0" ? "unlimited" : escapeHtml(effectiveAdmin)}/day</span>
+      </p>
+      ${numRow("rate_limit", "rate_limit", effectiveBurst)}
+      ${numRow("rate_limit.member", "rate_limit.member", effectiveMember)}
+      ${numRow("rate_limit.admin", "rate_limit.admin", effectiveAdmin)}
+    `;
+  }
+
   function renderModelBlock(cfg: AppConfig): string {
     const legs = cfg.resolvedModelChain;
     if (legs.length === 0) {
@@ -1077,6 +1142,7 @@ export function createDashboardRoutes(ctx: DashboardContext) {
     );
 
     const contextHtml = renderContextPanel(spaceId, spacePageReload);
+    const rateLimitHtml = renderRateLimitPanel(spaceId, spacePageReload);
 
     const configHtml =
       configEntriesFiltered.length > 0
@@ -1157,6 +1223,11 @@ export function createDashboardRoutes(ctx: DashboardContext) {
         <div class="panel-body">${raw(contextHtml)}</div>
       </div>
 
+      <div class="panel">
+        <div class="panel-header">Rate limits</div>
+        <div class="panel-body">${raw(rateLimitHtml)}</div>
+      </div>
+
       <div class="grid-2">
         <div class="panel">
           <div class="panel-header">Tasks</div>

package/src/core/runtime.ts

@@ -398,8 +398,17 @@ export class MercuryCoreRuntime {
       if (route.role !== "system") {
         const roleKey = `rate_limit.${route.role}`;
         const roleLimitRaw = this.db.getSpaceConfig(message.spaceId, roleKey);
-        if (roleLimitRaw !== null) {
-          const roleLimit = Number.parseInt(roleLimitRaw, 10);
+        const globalDailyLimit =
+          route.role === "member"
+            ? this.config.rateLimitDailyMember
+            : route.role === "admin"
+              ? this.config.rateLimitDailyAdmin
+              : 0;
+        const effectiveDailyRaw =
+          roleLimitRaw ??
+          (globalDailyLimit > 0 ? String(globalDailyLimit) : null);
+        if (effectiveDailyRaw !== null) {
+          const roleLimit = Number.parseInt(effectiveDailyRaw, 10);
           if (!Number.isNaN(roleLimit) && roleLimit > 0) {
             const daily = this.db.checkAndIncrementDailyUsage(
               message.spaceId,
@@ -416,7 +425,6 @@ export class MercuryCoreRuntime {
               };
             }
           }
-          // roleLimit === 0 means unlimited — skip daily check
         }
       }