level-up-mcp-server-cn 0.4.0

package/docs/v0.3-roadmap.md

@@ -0,0 +1,191 @@
+# v0.3 Roadmap
+
+## Release Theme: Bootstrap, Quests & UX
+
+Target: After v0.2.x feedback incorporated
+
+---
+
+## v0.2.x Review Summary (2026-03-17)
+
+Two reviews received — Claude (technical) and OpenClaw/Maine (user testing on Ken's account).
+
+**Key findings:**
+- User XP too low (2-6 XP per task due to 60/40 agent split) — users feel unrewarded
+- Class tracks (Trainer/Orchestrator/Partner) completely unused — 0 XP across all users
+- Output type rarely set (90% null), evidence rarely attached
+- Orphaned tasks — 2 tasks stuck in_progress with no recovery mechanism
+- No onboarding guidance — users don't know what to do next
+- 15+ tool calls needed for full onboarding — too much friction
+- Rating: 6/10 — good foundation, needs better UX
+
+---
+
+## v0.3 Build Order (by impact × feasibility)
+
+### Phase 1: CRITICAL — Unblock adoption
+
+#### 1. Session Bootstrap (`levelup_bootstrap`)
+Single tool call returns complete session state for stateless agents.
+
+```
+levelup_bootstrap(user_id?, agent_id?, platform?)
+→ Returns: user profile, agent profile, orphaned tasks, recent tasks,
+  active quests, coaching nudge, recovery actions
+```
+
+**Solves:** 3 sequential tool calls → 1. Orphaned task recovery. Works across fresh chats.
+
+#### 2. Setup Wizard (`levelup_setup_wizard`)
+One-call onboarding that auto-maps installed MCPs to skills.
+
+```
+levelup_setup_wizard(agent_id, installed_mcps?: string[], auto_register_skills?: true)
+→ Returns: skills_registered, skills_already_had, suggested_mcps, suggested_skills
+```
+
+**Solves:** 15+ tool calls → 1 for skill registration. MCP-to-skill lookup table built in.
+
+#### 3. Quest / Challenge System
+Directed learning through onboarding, skill, and weekly quests.
+
+**Onboarding quests:** "Register profile" → "Add 3 skills" → "Complete first task" → "Install 3 MCPs" → "Quality score > 3.5"
+**Skill quests:** "Use GitHub MCP to create a PR" → "Set up automated workflow with 2+ MCPs"
+**Weekly challenges:** "Complete 5 tasks" → "Increase skill proficiency" → "5-day streak"
+
+Tools: `levelup_get_active_quests`, `levelup_start_quest`, `levelup_check_quest_progress`
+Note: 12 quest tools already exist in quests.ts but are not active.
+
+### Phase 2: HIGH — Drive engagement
+
+#### 4. Fix Growth Plan Quality
+- Deduplicate MCP install suggestions (group skills-per-MCP)
+- Mix action types — max 3 installs before suggesting a task
+- Filter by already-installed MCPs
+- Differentiate priorities (critical/recommended/optional)
+- Respect 3/day install cooldown — spread across days
+
+#### 5. Contextual Coaching (`levelup_get_coaching_suggestions`)
+Analyzes task history, tool usage, automation ratio, skill gaps, unused MCPs.
+
+```
+levelup_get_coaching_suggestions(user_id, agent_id?, focus?)
+→ Returns: suggestions with evidence, impact, pre-filled action params
+```
+
+Example: "You've done 8 email drafts manually. Gmail MCP is installed but unused in tasks."
+
+#### 6. Workflow Templates (`levelup_browse_workflows`)
+Multi-step recipes using multiple MCPs. Shows which MCPs user has vs needs.
+
+Seed workflows: Bug fix pipeline, Feature sprint, Blog post pipeline, Meeting automation, etc.
+
+### Phase 3: MEDIUM — Polish & consolidate
+
+#### 7. Consolidated Dashboard (`levelup_dashboard`)
+One tool replaces 6+: user profile + progress + achievements + recap + agents + quests.
+
+#### 8. Idempotent Task Tracking (`levelup_resume_or_start`)
+Checks for in-progress task with similar title before creating new one. Auto-fail tasks orphaned 24h+.
+
+#### 9. Progressive Tool Disclosure
+Level 1-3: ~15 tools (basics). Level 4-7: +12 tools (intermediate). Level 8+: all tools (admin/power).
+
+#### 10. Achievement System Seeding
+Seed 30-50 achievements: First Steps, Century (100 XP), Rank Up, On a Roll (3-day streak), Craftsman (4.5+ quality), Night Owl, Speed Demon, Polyglot.
+
+### Phase 4: LOW — Future infrastructure
+
+#### 11. Webhook / Push Notifications
+Platforms subscribe to events: level_up, achievement_earned, quest_available, weekly_recap.
+
+#### 12. Testing Service (separate repo: level-up-test-service)
+See testing service architecture below.
+
+---
+
+## User XP Balance Fix
+
+**Problem:** Users get 40% of XP in user_with_agent tasks (60% to agent). Users earn 2-6 XP per task, feels unrewarding.
+
+**Options:**
+- A) Adjust default split to 50/50
+- B) Add user-only XP bonuses (evidence bonus, streak bonus, quest completion)
+- C) Both — rebalance split AND add user bonuses
+- D) Keep split but add class track XP (Trainer/Orchestrator/Partner earn separately)
+
+**Decision needed before v0.3.**
+
+---
+
+## Feature: Testing Service (deferred to v0.4+)
+
+### Architecture
+
+```
+Agent <-> Level-Up MCP <-> Testing Service (HTTP API)
+                               |
+                           Supabase DB
+```
+
+### Test Types
+
+| Type | Trigger | Purpose |
+|------|---------|---------|
+| Skill verification | Agent claims skill proficiency | Prove agent can actually use a skill |
+| Rank advancement | Agent at level 10 (D) -> 11 (C) | Gate or bonus for rank-up milestones |
+| Periodic re-test | Configurable interval | Prevent skill decay / stale claims |
+
+### Open Design Questions
+
+1. Gated vs optional — Must agents test to rank up, or just bonus XP?
+2. Evaluation method — LLM judge vs rubric checklist vs hybrid
+3. Challenge source — Fixed bank vs LLM-generated per attempt
+4. Cheating prevention — Time limits, unique challenges, cooldown, max attempts
+5. Deployment — Separate Railway service vs serverless
+
+---
+
+## Other Ideas (backlog)
+
+- [ ] MCP discovery tool — search Docker MCP registry / awesome-mcp-servers
+- [ ] Allow agents to install any MCP and map to closest ability category
+- [ ] Frontend experiment using Google Flow
+- [ ] Testing module experiment using Mirro (simulated AI reviewers)
+- [ ] `npx level-up-mcp-server --setup` auto-config command
+- [ ] Blockchain integration — on-chain XP/achievement verification, portable agent credentials
+- [ ] Class track activation (Trainer/Orchestrator/Partner)
+- [ ] User preference snippet generator for persistent identity
+- [ ] MCP-level session identity (requires MCP spec changes)
+- [ ] Auto-prompt users after tasks for output_type and evidence
+
+---
+
+## Completed (v0.2.x)
+
+- [x] Agents not earning XP — fixed agent_id flow (v0.2.2)
+- [x] Stars displayed in rank responses (v0.2.2)
+- [x] register_user/register_agent → RPC with fallback (v0.2.4)
+- [x] Achievement auto-triggers (v0.2.2)
+- [x] Skill discount passed to level-up RPC (v0.2.2)
+- [x] Tool installation XP +20 (v0.2.2)
+- [x] Whoami auto-detection (v0.2.5)
+- [x] Growth plan level-gating (v0.2.5)
+- [x] Evidence requirements per tier (v0.2.4)
+- [x] Browse skillsets — 18 categories (v0.2.4)
+- [x] check_level_up RPC fix (v0.2.6)
+- [x] Evidence sanitization pipeline (v0.2.1)
+- [x] Tier override + auto-downgrade (v0.2.1)
+- [x] Anti-gaming: quality gate, rate limiting, duration floors (v0.2.0)
+
+---
+
+## Versioning Plan
+
+| Version | Scope |
+|---------|-------|
+| 0.2.0-0.2.6 | Foundation — anti-gaming, evidence, growth plans, whoami, skillsets |
+| 0.3.0 | Bootstrap + setup wizard + quest system + growth plan fixes |
+| 0.3.x | Coaching, workflows, dashboard consolidation, achievements |
+| 0.4.0 | Testing service + progressive disclosure + webhooks |
+| 1.0.0 | Blockchain integration + stable API |

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "level-up-mcp-server-cn",
+  "version": "0.4.0",
+  "description": "Level-Up 游戏化MCP服务器 — 为人类和AI智能体追踪经验值、等级、技能和任务",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "level-up-mcp-server-cn": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "start:http": "TRANSPORT=http node dist/index.js",
+    "pretest": "rm -rf node_modules/.vite node_modules/.experimental-vitest-cache",
+    "test": "vitest run --pool forks",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@supabase/supabase-js": "^2.49.0",
+    "express": "^5.0.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "BUSL-1.1"
+}

package/sql/agent_pending_installs.sql

@@ -0,0 +1,28 @@
+-- agent_pending_installs: tracks frontend install requests before agent confirmation
+-- Flow: frontend INSERT (pending) → agent reads → agent installs → agent UPDATE (confirmed)
+
+CREATE TABLE IF NOT EXISTS agent_pending_installs (
+  id          uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  agent_id    uuid NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+  item_type   text NOT NULL CHECK (item_type IN ('mcp', 'skill')),
+  item_name   text NOT NULL,
+  status      text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'confirmed', 'cancelled')),
+  created_at  timestamptz DEFAULT now(),
+  confirmed_at timestamptz
+);
+
+-- Index for fast lookup by agent
+CREATE INDEX IF NOT EXISTS idx_pending_installs_agent
+  ON agent_pending_installs(agent_id, status);
+
+-- RLS: allow anon read/write for now (frontend uses anon key)
+ALTER TABLE agent_pending_installs ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "anon_read_pending_installs" ON agent_pending_installs
+  FOR SELECT TO anon USING (true);
+
+CREATE POLICY "anon_insert_pending_installs" ON agent_pending_installs
+  FOR INSERT TO anon WITH CHECK (true);
+
+CREATE POLICY "anon_update_pending_installs" ON agent_pending_installs
+  FOR UPDATE TO anon USING (true) WITH CHECK (true);

package/sql/award_class_xp.sql

@@ -0,0 +1,81 @@
+-- ============================================================
+-- RPC: award_class_xp
+-- Awards class XP to a user's class track (trainer/partner/orchestrator).
+-- Updates user_class_progress and records the XP in xp_ledger
+-- with the class name as xp_type.
+-- ============================================================
+CREATE OR REPLACE FUNCTION award_class_xp(
+  p_user_id UUID,
+  p_class_name TEXT,
+  p_amount INTEGER,
+  p_source_type TEXT,
+  p_description TEXT,
+  p_source_id UUID DEFAULT NULL
+) RETURNS JSONB AS $$
+DECLARE
+  v_class_row RECORD;
+  v_running_total BIGINT;
+BEGIN
+  -- Validate user exists
+  IF NOT EXISTS (SELECT 1 FROM users WHERE id = p_user_id) THEN
+    RETURN jsonb_build_object('success', false, 'error', 'User not found');
+  END IF;
+
+  -- Validate class name
+  IF p_class_name NOT IN ('trainer', 'partner', 'orchestrator') THEN
+    RETURN jsonb_build_object('success', false, 'error', 'Invalid class_name');
+  END IF;
+
+  -- Validate amount is positive
+  IF p_amount <= 0 THEN
+    RETURN jsonb_build_object('success', false, 'error', 'Amount must be positive');
+  END IF;
+
+  -- Get the class progress row
+  SELECT id, class_xp INTO v_class_row
+  FROM user_class_progress
+  WHERE user_id = p_user_id AND class_name = p_class_name;
+
+  IF NOT FOUND THEN
+    RETURN jsonb_build_object('success', false, 'error', 'Class progress row not found');
+  END IF;
+
+  -- Update class XP
+  UPDATE user_class_progress
+  SET class_xp = v_class_row.class_xp + p_amount
+  WHERE id = v_class_row.id;
+
+  -- Get running total for xp_ledger
+  SELECT COALESCE(running_total, 0) INTO v_running_total
+  FROM xp_ledger
+  WHERE entity_type = 'user' AND entity_id = p_user_id
+  ORDER BY created_at DESC
+  LIMIT 1;
+
+  IF NOT FOUND THEN
+    v_running_total := 0;
+  END IF;
+
+  -- Note: class XP is tracked separately; running_total here is for audit trail only
+  -- and does NOT get added to main_xp (class XP is a parallel track)
+
+  -- Insert ledger entry with class name as xp_type
+  INSERT INTO xp_ledger (
+    entity_type, entity_id, xp_type, amount,
+    source_type, source_id, description, running_total
+  ) VALUES (
+    'user', p_user_id, p_class_name, p_amount,
+    p_source_type, p_source_id, p_description, v_running_total
+  );
+
+  RETURN jsonb_build_object(
+    'success', true,
+    'class_name', p_class_name,
+    'new_class_xp', v_class_row.class_xp + p_amount,
+    'amount', p_amount
+  );
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Grant access to anon role
+GRANT EXECUTE ON FUNCTION award_class_xp(UUID, TEXT, INTEGER, TEXT, TEXT, UUID) TO anon;

package/supabase/.temp/cli-latest

@@ -0,0 +1 @@
+v2.78.1

package/supabase/.temp/gotrue-version

@@ -0,0 +1 @@
+v2.187.0

package/supabase/.temp/pooler-url

@@ -0,0 +1 @@
+postgresql://postgres.pxanrmpwptinbtwigqdt@aws-1-ap-southeast-1.pooler.supabase.com:5432/postgres

package/supabase/.temp/postgres-version

@@ -0,0 +1 @@
+17.6.1.084

package/supabase/.temp/project-ref

@@ -0,0 +1 @@
+pxanrmpwptinbtwigqdt

package/supabase/.temp/rest-version

@@ -0,0 +1 @@
+v14.4

package/supabase/.temp/storage-migration

@@ -0,0 +1 @@
+fix-optimized-search-function

package/supabase/.temp/storage-version

@@ -0,0 +1 @@
+v1.37.7

package/supabase/migrations/20260314000000_anon_rls_policies.sql

@@ -0,0 +1,311 @@
+-- ============================================================
+-- Migration: Add anon role RLS policies for MCP server
+-- ============================================================
+-- The MCP server connects with the anon key (no auth.uid()).
+-- These policies allow the MCP tools to perform core operations
+-- while keeping XP/level columns locked to SECURITY DEFINER RPCs.
+--
+-- EXISTING anon policies (already in place, DO NOT re-create):
+--   anon SELECT on: users, user_identities, user_class_progress,
+--     user_achievements, user_level_requirements, agents, agent_skills,
+--     agent_tool_installations, agent_skill_snapshots, agent_transfers,
+--     agent_integrity_log, agent_cross_ratings, skills, tasks,
+--     weekly_bonus_criteria, achievement_definitions, verification_rules,
+--     + all reference tables (level_curves, rank_definitions, xp_config, etc.)
+--   anon INSERT on: user_identities, agent_skills, agent_skill_snapshots,
+--     agent_transfers, agent_integrity_log, agent_cross_ratings, skills,
+--     agent_tool_installations, user_level_requirements
+--   anon UPDATE on: user_identities, user_level_requirements, agent_skills
+--
+-- STRATEGY:
+--   - XP/level writes → only via SECURITY DEFINER RPCs (locked)
+--   - Task/agent/user creation → anon INSERT allowed (MCP tools enforce rules)
+--   - Config/rule tables → read-only for anon (admin via service_role)
+-- ============================================================
+
+-- ============================================================
+-- 1. USERS: Allow registration and safe profile updates
+-- ============================================================
+
+-- Anon can register new users
+CREATE POLICY "anon_insert_users" ON users
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+-- NO anon UPDATE on users — all updates go through RPCs:
+--   update_user_profile()   for safe fields
+--   merge_user_profiles()   for profile merges
+--   award_task_xp()         for XP (existing)
+--   check_and_apply_level_up() for levels (existing)
+
+-- ============================================================
+-- 2. USER_CLASS_PROGRESS: Allow creation during registration
+-- ============================================================
+
+CREATE POLICY "anon_insert_user_class_progress" ON user_class_progress
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+-- NO anon UPDATE on user_class_progress — updates via RPCs only
+
+-- ============================================================
+-- 3. AGENTS: Allow registration, safe updates only
+-- ============================================================
+
+-- Anon can register agents
+CREATE POLICY "anon_insert_agents" ON agents
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+-- NO anon UPDATE on agents — all updates go through RPCs:
+--   update_agent_profile()     for safe fields (with ownership check)
+--   update_integrity_score()   for integrity
+--   record_level_up_timestamp() for level-up timestamps
+--   award_task_xp()            for XP (existing)
+--   check_and_apply_level_up() for levels (existing)
+
+-- ============================================================
+-- 4. TASKS: Allow create and update (MCP enforces min duration,
+--    rate limits, cooldowns)
+-- ============================================================
+
+CREATE POLICY "anon_insert_tasks" ON tasks
+  FOR INSERT TO anon
+  WITH CHECK (
+    status = 'in_progress'  -- Can only create tasks as in_progress
+  );
+
+-- NO anon UPDATE on tasks — all updates go through update_task_status() RPC
+-- which verifies the caller owns the task
+
+-- ============================================================
+-- 5. TASK SUPPORT TABLES: Ratings, expectations, evaluations, TDI
+-- ============================================================
+
+CREATE POLICY "anon_insert_task_ratings" ON task_ratings
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_insert_task_expectations" ON task_expectations
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_read_task_evaluations" ON task_evaluations
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_task_evaluations" ON task_evaluations
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_read_task_milestones" ON task_milestones
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_task_milestones" ON task_milestones
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_update_task_milestones" ON task_milestones
+  FOR UPDATE TO anon
+  USING (true)
+  WITH CHECK (true);
+
+-- TDI: Allow MCP to upsert difficulty index entries
+CREATE POLICY "anon_insert_task_difficulty_index" ON task_difficulty_index
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_update_task_difficulty_index" ON task_difficulty_index
+  FOR UPDATE TO anon
+  USING (true)
+  WITH CHECK (true);
+
+-- Task XP awards: read-only for anon (written by award_task_xp RPC)
+CREATE POLICY "anon_read_task_xp_awards" ON task_xp_awards
+  FOR SELECT TO anon
+  USING (true);
+
+-- ============================================================
+-- 6. QUESTS: Allow create, join, progress, complete
+-- ============================================================
+
+CREATE POLICY "anon_read_quests" ON quests
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_quests" ON quests
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_update_quests" ON quests
+  FOR UPDATE TO anon
+  USING (true)
+  WITH CHECK (true);
+
+CREATE POLICY "anon_read_quest_participants" ON quest_participants
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_quest_participants" ON quest_participants
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_read_quest_completions" ON quest_completions
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_quest_completions" ON quest_completions
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+-- ============================================================
+-- 7. LINK CODES & OTP: Allow MCP to create codes
+-- ============================================================
+
+CREATE POLICY "anon_read_link_codes" ON link_codes
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_link_codes" ON link_codes
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_update_link_codes" ON link_codes
+  FOR UPDATE TO anon
+  USING (true)
+  WITH CHECK (true);
+
+-- OTP codes (if table exists with RLS enabled)
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'public' AND tablename = 'otp_codes') THEN
+    EXECUTE 'CREATE POLICY "anon_read_otp_codes" ON otp_codes FOR SELECT TO anon USING (true)';
+    EXECUTE 'CREATE POLICY "anon_insert_otp_codes" ON otp_codes FOR INSERT TO anon WITH CHECK (true)';
+    EXECUTE 'CREATE POLICY "anon_update_otp_codes" ON otp_codes FOR UPDATE TO anon USING (true) WITH CHECK (true)';
+    EXECUTE 'CREATE POLICY "anon_delete_otp_codes" ON otp_codes FOR DELETE TO anon USING (true)';
+  END IF;
+END $$;
+
+-- ============================================================
+-- 8. METRICS: Allow reporting and processing
+-- ============================================================
+
+CREATE POLICY "anon_read_metrics_log" ON metrics_log
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_metrics_log" ON metrics_log
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+CREATE POLICY "anon_update_metrics_log" ON metrics_log
+  FOR UPDATE TO anon
+  USING (true)
+  WITH CHECK (true);
+
+-- ============================================================
+-- 9. WEEKLY BONUSES: Allow processing
+-- ============================================================
+
+CREATE POLICY "anon_read_weekly_bonus_awards" ON weekly_bonus_awards
+  FOR SELECT TO anon
+  USING (true);
+
+CREATE POLICY "anon_insert_weekly_bonus_awards" ON weekly_bonus_awards
+  FOR INSERT TO anon
+  WITH CHECK (true);
+
+-- Weekly bonus progress (if exists)
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'public' AND tablename = 'weekly_bonus_progress') THEN
+    EXECUTE 'CREATE POLICY "anon_read_weekly_bonus_progress" ON weekly_bonus_progress FOR SELECT TO anon USING (true)';
+    EXECUTE 'CREATE POLICY "anon_insert_weekly_bonus_progress" ON weekly_bonus_progress FOR INSERT TO anon WITH CHECK (true)';
+    EXECUTE 'CREATE POLICY "anon_update_weekly_bonus_progress" ON weekly_bonus_progress FOR UPDATE TO anon USING (true) WITH CHECK (true)';
+  END IF;
+END $$;
+
+-- ============================================================
+-- 10. XP LEDGER: READ-ONLY for anon (LOCKED)
+-- ============================================================
+-- xp_ledger has NO anon insert/update policy — this is correct.
+-- All XP writes go through SECURITY DEFINER RPCs:
+--   - award_task_xp (task completion)
+--   - check_and_apply_level_up (level progression)
+--
+-- The awardXpWithLock() function in quests.ts writes directly
+-- to xp_ledger — this will FAIL with anon key. It must be
+-- migrated to a SECURITY DEFINER RPC. See migration note below.
+
+CREATE POLICY "anon_read_xp_ledger" ON xp_ledger
+  FOR SELECT TO anon
+  USING (true);
+
+-- ============================================================
+-- 11. ADMIN-ONLY TABLES: No anon write (use service_role key)
+-- ============================================================
+-- These tables have anon SELECT but intentionally NO anon write:
+--   - task_types (create_task_type is admin-only)
+--   - xp_config (set_xp_config is admin-only)
+--   - xp_split_rules / xp_split_rule_entries (create_split_rule is admin-only)
+--   - level_curves, rank_definitions, completion_curves
+--   - skill_categories, skill_leveling_rules, skill_tool_mappings
+--   - achievement_definitions, community_expectations
+--
+-- Admin tools (Section 12) must use service_role key to write to these.
+
+-- ============================================================
+-- 12. ENSURE RPCs ARE SECURITY DEFINER
+-- ============================================================
+-- These functions must bypass RLS to update locked XP/level columns.
+-- Run these ALTER statements to confirm they're SECURITY DEFINER:
+
+ALTER FUNCTION award_task_xp(uuid) SECURITY DEFINER;
+ALTER FUNCTION check_and_apply_level_up(text, uuid) SECURITY DEFINER;
+
+-- ============================================================
+-- MIGRATION NOTE: awardXpWithLock() needs an RPC
+-- ============================================================
+-- The quest/weekly-bonus XP path in the MCP server currently
+-- writes directly to xp_ledger and updates users.main_xp / agents.xp.
+-- With these RLS policies, that path will fail for anon.
+--
+-- TODO: Create a new SECURITY DEFINER RPC:
+--
+--   CREATE OR REPLACE FUNCTION award_xp_direct(
+--     p_entity_type TEXT,
+--     p_entity_id UUID,
+--     p_amount INTEGER,
+--     p_source_type TEXT,
+--     p_description TEXT,
+--     p_source_id UUID DEFAULT NULL
+--   ) RETURNS JSONB AS $$
+--   DECLARE
+--     v_running_total BIGINT;
+--   BEGIN
+--     SELECT COALESCE(running_total, 0) INTO v_running_total
+--     FROM xp_ledger
+--     WHERE entity_type = p_entity_type AND entity_id = p_entity_id
+--     ORDER BY created_at DESC LIMIT 1;
+--
+--     v_running_total := v_running_total + p_amount;
+--
+--     INSERT INTO xp_ledger (entity_type, entity_id, xp_type, amount,
+--       source_type, source_id, description, running_total)
+--     VALUES (p_entity_type, p_entity_id, 'main', p_amount,
+--       p_source_type, p_source_id, p_description, v_running_total);
+--
+--     IF p_entity_type = 'user' THEN
+--       UPDATE users SET main_xp = v_running_total WHERE id = p_entity_id;
+--     ELSE
+--       UPDATE agents SET xp = v_running_total WHERE id = p_entity_id;
+--     END IF;
+--
+--     RETURN jsonb_build_object('success', true, 'running_total', v_running_total);
+--   END;
+--   $$ LANGUAGE plpgsql SECURITY DEFINER;
+--
+-- Then update quests.ts awardXpWithLock() to call this RPC instead
+-- of writing directly to xp_ledger.
+-- ============================================================