@bolloon/bolloon-agent 0.1.0

package/src/bollharness/reference/boll-reference/.claude/rules/backend-routes.md

@@ -0,0 +1,268 @@
+---
+paths:
+  - "backend/product/routes/**"
+  - "backend/server.py"
+  - "backend/product/protocol/**"
+  - "backend/product/auth/**"
+  - "backend/product/coaching/**"
+  - "backend/product/hackathon/**"
+  - "backend/product/bridge/**"
+  - "backend/product/a2a/**"
+  - "backend/product/matching/**"
+  - "backend/product/messaging/**"
+  - "backend/product/public_profiles/**"
+  - "backend/product/inbox/**"
+  - "mcp-server/boll_mcp/**"
+  - "mcp-server-node/src/**"
+---
+
+# Runtime Routes
+
+## Core
+- `GET /health`
+
+## Field API (`/field/api`)
+- `GET /field/api/stats`
+- `POST /field/api/deposit` (**admin-only**)
+- `POST /field/api/load-profiles` (**admin-only**)
+- `POST /field/api/match-perspectives` (**admin-only**)
+- `POST /field/api/match`
+- `POST /field/api/match-owners`
+
+## Product API (`/api`)
+- `POST /api/register` — invite-code + email registration
+- `POST /api/login` — email + password login
+- `POST /api/logout` — session logout
+- `PUT /api/change-password` — change password (session auth)
+- `GET /api/profile` — get current user profile
+- `PUT /api/profile` — update profile
+- `PATCH /api/profile/visibility` — toggle profile visibility
+- `GET /api/ws-ticket` — WebSocket auth ticket
+- `POST /api/demands` — create demand (clarification-session)
+- `PUT /api/demands/{demand_id}/confirm` — confirm demand
+- `POST /api/demands/{demand_id}/start` — start convergence run
+- `GET /api/demands` — list user demands
+- `GET /api/demands/{demand_id}` — demand detail
+- `GET /api/runs/{run_id}` — run status (+ participant_names)
+- `GET /api/runs/{run_id}/result` — run result (+ participant_names)
+- `WS /ws/runs/{run_id}` — run progress WebSocket
+- `POST /api/admin/invite-codes` (**admin-only**)
+- `POST /api/admin/stream-token` (**admin-only**) — SSE auth token
+- `GET /api/admin/stream` (**admin-only**) — SSE event stream
+- `GET /api/admin/bridges` (**admin-only**) — bridge instance status
+- `GET /api/admin/runs` (**admin-only**) — runs list with filters
+- `GET /api/admin/runs/{run_id}/events` (**admin-only**) — run event log
+- `GET /api/admin/invite-chain` (**admin-only**) — invite tree tracing (PLAN-064)
+- `GET /api/admin/usage/overview` (**admin-only**) — usage analytics overview
+- `GET /api/admin/usage/events` (**admin-only**) — usage event log
+- `GET /api/admin/usage/report` (**admin-only**) — usage report
+- `GET /api/admin/users-overview` (**admin-only**) — all users overview
+- `GET /api/admin/users/{user_id}/sessions` (**admin-only**) — user session history
+- `GET /api/admin/sessions/turns` (**admin-only**) — session turns across users
+- `GET /api/admin/config/status` (**admin-only**) — server config status
+- `GET /api/dashboard` — user dashboard data
+- `GET /api/metrics/platform` — platform-wide metrics
+
+## Coaching API (`/api/coaching`)
+- `POST /api/coaching/chat` — create a coaching session and stream first reply
+- `POST /api/coaching/chat/{session_id}` — continue an existing coaching session
+- `POST /api/coaching/report/{session_id}` — stream report generation for a session
+- `GET /api/coaching/sessions` — list coaching sessions for current account
+- `GET /api/coaching/sessions/{session_id}` — get coaching session detail
+- `GET /api/coaching/sessions/{session_id}/report` — fetch persisted coaching report
+- `POST /api/coaching/sync-profile` — sync user coaching profile to protocol layer
+- `PUT /api/coaching/profile` — update user coaching profile
+- `PATCH /api/coaching/sessions/{session_id}/title` — rename a coaching session
+- `DELETE /api/coaching/sessions/{session_id}` — delete a coaching session
+- `GET /api/coaching/profile` — get user coaching profile (profile_fields + coaching_fields + insight_overrides)
+- `POST /api/coaching/profile-chat` — AI profile assistant SSE chat (no session creation)
+- `PATCH /api/coaching/insight-overrides` — confirm/reject/edit AI-extracted insights
+- `GET /api/coaching/operations` — list async operations (find_people/daily_surprise)
+- `POST /api/coaching/behavior` — record share/download/copy behavior metrics
+- `GET /api/coaching/settings/dream-consent` — get dream opt-in status
+- `PUT /api/coaching/settings/dream-consent` — toggle dream opt-in
+- `POST /api/coaching/dream-now` — manually trigger dream consolidation for today
+- `GET /api/coaching/growth-logs` — list growth log entries
+- `PATCH /api/coaching/growth-logs/{log_id}/share` — share growth log to plaza (anonymized)
+- `DELETE /api/coaching/growth-logs/{log_id}/share` — revoke sharing (72h window)
+- `GET /api/coaching/plaza` — **unauthenticated** browse anonymized growth logs (rate-limited: 60/min/IP)
+
+## Coaching Admin API (`/api/coaching/admin`, **admin-only**)
+- `GET /api/coaching/admin/users` — list coaching users with session counts
+- `GET /api/coaching/admin/users/{account_id}` — get coaching panorama for one user
+- `GET /api/coaching/admin/users/{account_id}/export` — export one user's coaching data
+- `GET /api/coaching/admin/prompts` — list prompt versions for coaching prompts
+- `PUT /api/coaching/admin/prompts/{prompt_name}` — create and activate a prompt version
+- `POST /api/coaching/admin/prompts/{prompt_name}/preview` — render a prompt template without persisting
+- `GET /api/coaching/admin/export` — export all coaching data
+- `GET /api/coaching/admin/strategy` (**admin-only**) — get coaching strategy config (internal)
+- `PUT /api/coaching/admin/strategy/{config_key}` (**admin-only**) — update coaching strategy config (internal)
+- `GET /api/coaching/admin/operations` (**admin-only**) — list async operations (internal)
+- `POST /api/coaching/admin/operations/{operation_id}/retry` (**admin-only**) — retry failed operation (internal)
+- `GET /api/coaching/admin/scheduler-health` (**admin-only**) — coaching scheduler health (internal)
+
+## Hackathon API (`/api/hackathon`, **session auth**)
+- `POST /api/hackathon/events` — create hackathon event (**organizer**)
+- `GET /api/hackathon/events` — list events
+- `GET /api/hackathon/events/{event_id}` — event detail
+- `PUT /api/hackathon/events/{event_id}` — update event (**organizer**)
+- `PATCH /api/hackathon/events/{event_id}/status` — transition event status (**organizer**)
+- `POST /api/hackathon/events/{event_id}/invite` — generate invite codes (**organizer**)
+- `POST /api/hackathon/events/{event_id}/enrollments` — enroll in event
+- `GET /api/hackathon/events/{event_id}/enrollments` — list enrollments
+- `GET /api/hackathon/events/{event_id}/enrollments/mine` — my enrollment
+- `PATCH /api/hackathon/enrollments/{enrollment_id}` — update enrollment role (**organizer**)
+- `POST /api/hackathon/events/{event_id}/teams` — create team
+- `GET /api/hackathon/events/{event_id}/teams` — list teams
+- `GET /api/hackathon/teams/{team_id}` — team detail
+- `POST /api/hackathon/teams/{team_id}/members` — add team member
+- `DELETE /api/hackathon/teams/{team_id}/members/{agent_id}` — remove team member
+- `PATCH /api/hackathon/teams/{team_id}/status` — update team status
+- `POST /api/hackathon/teams/{team_id}/claim` — claim challenge
+- `POST /api/hackathon/events/{event_id}/challenges` — create challenge (**organizer**)
+- `GET /api/hackathon/events/{event_id}/challenges` — list challenges
+- `POST /api/hackathon/teams/{team_id}/submit` — submit deliverables
+- `GET /api/hackathon/events/{event_id}/reviews/assignments` — get review assignments (**judge**)
+- `POST /api/hackathon/reviews` — submit review (**judge**)
+- `GET /api/hackathon/events/{event_id}/reviews/summary` — review summary (**organizer**)
+- `GET /api/hackathon/teams/{team_id}/reviews` — team reviews
+- `POST /api/hackathon/upload/sts-token` — get OSS upload token
+- `GET /api/hackathon/events/{event_id}/stats` — event statistics
+- `POST /api/hackathon/events/{event_id}/import` — bulk import participants (**organizer**)
+- `GET /api/hackathon/events/{event_id}/import/{job_id}` — import job status
+
+## Public API (`/api/public`, **unauthenticated**, PLAN-064)
+- `POST /api/public/registration-chat` — SSE streaming registration chat (rate-limited: 10 req/min/IP)
+
+## Scene API (`/api/scene` + `/api/auth/secondme`)
+- `GET /api/auth/secondme/url` — SecondMe OAuth URL
+- `GET /api/auth/secondme/callback` — SecondMe OAuth callback (browser redirect)
+- `POST /api/auth/secondme/callback` — SecondMe OAuth callback (JSON API)
+- `POST /api/auth/secondme/register` — SecondMe register
+- `POST /api/auth/secondme/bind` — SecondMe bind to existing account
+- `POST /api/scene/chat` — SSE streaming scene chat
+
+## A2A Protocol API (`/a2a` + `/.well-known`)
+- `GET /.well-known/agent-card.json` — A2A agent card matching
+- `GET /a2a/extendedAgentCard` — extended agent card
+- `POST /a2a/message:send` — send A2A message
+- `POST /a2a/message:stream` — stream A2A message
+- `GET /a2a/tasks/{task_id}` — get A2A task
+- `GET /a2a/tasks` — list A2A tasks
+
+## Discovery Agent API (`/api/matching`)
+- `GET /api/matching/agents/{agent_id}/recommendations` — list recommendations for agent
+- `POST /api/matching/agents/{agent_id}/feedback` — submit matching feedback
+- `GET /api/matching/agents/{agent_id}/status` — get agent matching status
+
+## Plaza API (`/api/plaza`, **unauthenticated**)
+- `GET /api/plaza/profiles` — list community profiles
+- `GET /api/plaza/profiles/{user_id}` — get community profile detail
+- `GET /api/plaza/projects` — list community projects
+- `GET /api/plaza/demands` — list community demands
+
+## Public Profiles API (`/api/public-profiles`)
+- `PUT /api/public-profiles/{agent_id}` — update public profile
+- `GET /api/public-profiles` — list public directory
+- `GET /api/public-profiles/lookup` — lookup public profiles
+- `GET /api/public-profiles/{agent_id}` — get public profile
+
+## DID API
+- `GET /user/{account_id}/did.json` — account-level DID document
+
+## Bridge API (`/api/bridge`, **bridge-key auth**)
+- `GET /api/bridge/pending` — poll pending runs
+- `POST /api/bridge/accept` — accept a run
+- `POST /api/bridge/heartbeat` — heartbeat
+- `POST /api/bridge/events` — push progress events
+- `POST /api/bridge/complete` — complete a run
+
+## Protocol API (`/protocol`, **session-token auth**, MCP Server target)
+- `GET /protocol` — protocol metadata + encoding package summary
+- `GET /protocol/encoding-package` — full encoding package
+- `GET /protocol/agents/{agent_id}/federation` — federation metadata
+- `GET /protocol/agents/{agent_id}/did.json` — DID document
+- `POST /protocol/auth/register` — register account + default agent
+- `POST /protocol/auth/login` — login
+- `POST /protocol/auth/consumer-sessions` — create consumer auth session (PLAN-064)
+- `GET /protocol/auth/consumer-sessions/{auth_session_id}` — get consumer session state (PLAN-064)
+- `POST /protocol/auth/consumer-sessions/{auth_session_id}/exchange` — exchange challenge for token (PLAN-064)
+- `POST /protocol/auth/anp/challenge` — ANP DID challenge generation (PLAN-064)
+- `POST /protocol/auth/anp/verify` — ANP DID signature verification (PLAN-064)
+- `POST /protocol/auth/token` — refresh session token
+- `POST /protocol/auth/logout` — logout
+- `POST /protocol/auth/change-password` — change password
+- `POST /protocol/auth/forgot-password` — request password reset (PLAN-064)
+- `POST /protocol/auth/reset-password` — reset password with token (PLAN-064)
+- `DELETE /protocol/auth/account` — delete account (PLAN-064)
+- `POST /protocol/auth/byok-session` — bind BYOK API key (supports Anthropic + compatible providers: minimax; optional `base_url` for relay)
+- `GET /protocol/auth/byok-session` — check BYOK status
+- `DELETE /protocol/auth/byok-session` — clear BYOK binding
+- `POST /protocol/auth/redeem-code` — redeem invite code → +30 quota bonus (PLAN-085 WP-03)
+- `GET /protocol/account` — get current account metadata (PLAN-064)
+- `POST /protocol/account/email/verification` — request email verification (PLAN-064)
+- `GET /protocol/account/email/verify` — email verification callback (PLAN-064)
+- `GET /protocol/inbox` — list inbox items (PLAN-064)
+- `GET /protocol/inbox/{item_id}` — get inbox item detail (PLAN-064)
+- `POST /protocol/inbox/{item_id}/read` — mark inbox item as read (PLAN-064)
+- `POST /protocol/agents` — create agent
+- `GET /protocol/agents` — list agents
+- `GET /protocol/agents/public` — list public agents directory (PLAN-064)
+- `GET /protocol/agents/public/{agent_id}` — get public agent detail (PLAN-064)
+- `GET /protocol/agents/{agent_id}` — get agent detail
+- `GET /protocol/agents/{agent_id}/quality` — get agent profile quality score (PLAN-064)
+- `PUT /protocol/agents/{agent_id}` — update agent
+- `PATCH /protocol/agents/{agent_id}/visibility` — set visibility
+- `DELETE /protocol/agents/{agent_id}` — delete agent
+- `GET /protocol/invite-codes` — list user's own invite codes (PLAN-064)
+- `GET /protocol/demands/public` — list public demands (PLAN-064)
+- `GET /protocol/demands/public/{demand_id}` — get public demand detail (PLAN-064)
+- `PATCH /protocol/demands/{demand_id}/visibility` — toggle demand visibility (PLAN-064)
+- `GET /protocol/talent-pool` — list talent pool (PLAN-064)
+- `POST /protocol/talent-pool` — add agent to talent pool (PLAN-064)
+- `PUT /protocol/talent-pool/{agent_id}` — update talent pool entry (PLAN-064)
+- `DELETE /protocol/talent-pool/{agent_id}` — remove from talent pool (PLAN-064)
+- `GET /protocol/notifications/stream` — SSE notifications stream (PLAN-064)
+- `POST /protocol/clarification-sessions` — start clarification-session session
+- `GET /protocol/clarification-sessions/{session_id}` — get clarification-session state
+- `POST /protocol/clarification-sessions/{session_id}/reply` — continue clarification-session (SSE)
+- `POST /protocol/clarification-sessions/{session_id}/confirm` — confirm + trigger matching; when `start_negotiation=true`, also starts hosted negotiation
+- `POST /protocol/discover` — ad-hoc matching query; when `start_negotiation=true`, also starts hosted negotiation
+- `GET /protocol/discover/{query_id}` — get matching results
+- `POST /protocol/discover/{query_id}/rerun` — re-run existing matching (PLAN-064)
+- `GET /protocol/recommendations/{recommendation_id}` — get recommendation detail
+- `POST /protocol/invitations` — create invitation
+- `GET /protocol/invitations` — list invitations
+- `GET /protocol/invitations/{invitation_id}` — get invitation
+- `PATCH /protocol/invitations/{invitation_id}` — accept/decline invitation
+- `GET /protocol/runs/public` — list public runs (PLAN-064)
+- `GET /protocol/runs/public/{run_id}` — get public run detail (PLAN-064)
+- `GET /protocol/runs/public/{run_id}/result` — get public run result (PLAN-064)
+- `PATCH /protocol/runs/{run_id}/visibility` — toggle run visibility (PLAN-064)
+- `POST /protocol/runs` — legacy invitation-based run creation
+- `GET /protocol/runs/{run_id}` — run status
+- `GET /protocol/runs/{run_id}/prompt` — get current round prompt
+- `POST /protocol/runs/{run_id}/respond` — submit participant response
+- `GET /protocol/runs/{run_id}/result` — get run result
+- `WS /protocol/runs/{run_id}/stream` — run progress WebSocket
+- `POST /protocol/feedback` — submit feedback
+- `GET /protocol/usage` — usage stats
+- `GET /protocol/scenes` — list available scenes (PLAN-064)
+- `GET /protocol/scenes/{scene_id}` — get scene configuration (PLAN-064)
+- `POST /protocol/conversations` — send message (inter-agent messaging)
+- `GET /protocol/conversations` — list conversations
+- `GET /protocol/conversations/{conversation_id}/messages` — get conversation messages
+- `POST /protocol/conversations/{conversation_id}/read` — mark conversation as read
+
+## Auth Lanes
+- `GET /api/lanes/secondme_ai/callback` — SecondMe AI lane OAuth callback (HTML)
+
+## Auth Headers
+
+Admin-only routes require `boll_ADMIN_KEY` via either:
+- `X-Admin-Key: <key>`
+- `Authorization: Bearer <key>`
+
+Bridge routes require `BRIDGE_API_KEY` via `Authorization: Bearer <key>`.
+
+Protocol routes require session token via `Authorization: Bearer <session_token>` and accept `application/vnd.boll.v1+json`.

package/src/bollharness/reference/boll-reference/.claude/rules/bridge.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - "bridge_agent/**"
+  - "backend/product/bridge/**"
+  - "bridge_contract/**"
+---
+
+# Bridge 宪法 (ADR-026)
+
+Bridge 是薄中继，不是本地 orchestrator。以下 5 条规则约束所有 bridge 改动：
+
+1. **Worker 不拥有业务解释权，只上报执行事实。** 如果一段 worker 代码需要理解输出内容的含义，它就写错了地方。
+2. **同一个语义只允许有一个定义。** 不管是文件名模式、artifact 类型、还是 event 含义，只能在一个地方定义。
+3. **跑通了就发结果，没跑通就报 failed。** 不做 partial_success 抢救、不生成 placeholder、不从失败 stdout 里猜内容。这些如果需要，由 server 决定。
+4. **生产不能是第一个集成环境。** 本地必须能用 fake CLI + 真实 HTTP backend 跑完整链。
+5. **新增观测维度或 event 类型，只改 server，不改 worker。** 这是开闭原则的具体体现。
+
+三层职责：`boll-run` 定义成功产物契约 → `worker` 执行和上报事实 → `server` 解释事实并生成产品语义。
+
+详见: `docs/decisions/ADR-026-bridge-thin-relay-architecture.md`

package/src/bollharness/reference/boll-reference/.claude/rules/closure-semantics.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "docs/issues/**"
+  - "docs/decisions/ADR-030*"
+  - "scripts/hooks/**"
+---
+
+# Closure Semantics (ADR-030)
+
+## Fixed 三层定义
+
+Issue 标记 "Fixed" 不等于"症状消失"。三个层级：
+
+| 层级 | 含义 | 标准 | 标记 |
+|------|------|------|------|
+| Level 1 | 症状消失 | 生产不报错了，但没有分析复发路径 | Runtime Fixed |
+| Level 2 | 复发路径关闭 | 修了根因，分析了复发路径，写了 prevention_status | **Fixed** |
+| Level 3 | 机制消灭 | Fixed + 有机械化 guard 自动检测防止复发 | Fixed + Guarded |
+
+## Issue Doc YAML Frontmatter 规范
+
+所有 `docs/issues/` 下的 issue 文档必须包含以下 frontmatter 字段：
+
+```yaml
+status: fixed|open|wont_fix           # 当前状态
+prevention_status: open|closed        # 复发预防是否闭环
+mechanism_layer: guard|test|type|convention  # 防护机制层级
+```
+
+详见: `docs/decisions/ADR-030-guard-signal-protocol-and-governance-reload.md`

package/src/bollharness/reference/boll-reference/.claude/rules/coaching.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "scenes/example-coach/**"
+  - "backend/product/coaching/**"
+  - "backend/product/routes/coaching*.py"
+---
+
+# example-coach（kunzhi-coach）开发规则
+
+- 独立上下文：`scenes/example-coach/CLAUDE.md` 是专属开发指南
+- 协议接口契约：`scenes/example-coach/docs/PROTOCOL-CONTRACT.md` 定义与协议的精确依赖
+- 高危模式：`scenes/example-coach/docs/ERROR-PATTERNS.md` 列出 6 个 coaching 专属错误模式
+- 两套语言：协议术语和用户语言严格分离，场景用户永远不接触协议内部概念

package/src/bollharness/reference/boll-reference/.claude/rules/env-vars.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "backend/product/config.py"
+  - "backend/server.py"
+  - "scripts/deploy*.sh"
+  - "scripts/deploy*.py"
+  - ".env*"
+---
+
+# Important Environment Variables
+
+## Required
+- `DATABASE_URL` — PostgreSQL connection string
+- `BRIDGE_API_KEY` — bridge agent authentication
+- `boll_ADMIN_KEY` — admin route authentication
+
+## Optional
+- `ALLOWED_ORIGINS` — CORS origins (default includes localhost + <NETWORK_REDACTED> + <NETWORK_REDACTED> + auth.<NETWORK_REDACTED> + hackathon domains; see `backend/product/config.py`)
+- `boll_ANTHROPIC_API_KEY` — single API key (enables MPG)
+- `boll_ANTHROPIC_API_KEYS` — comma-separated API keys (rotation)
+- `boll_ANTHROPIC_BASE_URL` — custom API base URL
+- `SESSION_TTL_DAYS` — session expiry (default: 30)
+- `BCRYPT_ROUNDS` — password hash rounds (default: 12)
+- `LOGIN_MAX_ATTEMPTS_PER_MINUTE` — rate limit (default: 5)
+- `LOGIN_FREEZE_AFTER_FAILURES` — lockout threshold (default: 10)
+- `LOGIN_FREEZE_MINUTES` — lockout duration (default: 15)
+
+## Secrets (production-only)
+- `boll_KEY_ENCRYPTION_SECRET` — BYOK key encryption
+- `boll_PROTOCOL_ENCODING_PACKAGE_SECRET` — encoding package signing
+- `boll_PROTOCOL_FEDERATION_SECRET` — federation auth
+- `boll_OSS_ACCESS_KEY_ID` / `boll_OSS_ACCESS_KEY_SECRET` / `boll_OSS_ROLE_ARN` — Alibaba Cloud OSS
+- `boll_SMTP_HOST` / `boll_SMTP_PORT` / `boll_SMTP_USERNAME` / `boll_SMTP_PASSWORD` / `boll_SMTP_SENDER` / `boll_SMTP_USE_TLS` — email delivery
+- `SECONDME_CLIENT_ID` / `SECONDME_CLIENT_SECRET` / `SECONDME_REDIRECT_URI` — SecondMe OAuth
+
+## LLM Configuration
+- `boll_DEFAULT_MODEL` — default LLM model
+- `boll_COACHING_ANTHROPIC_API_KEY` / `boll_COACHING_ANTHROPIC_BASE_URL` / `boll_COACHING_ANTHROPIC_MODEL` — coaching-specific LLM
+- `boll_OPENROUTER_API_KEY` / `boll_OPENROUTER_BASE_URL` / `boll_OPENROUTER_MODEL` — OpenRouter fallback
+
+## Operational
+- `boll_SECURE_COOKIES` — cookie security flag (default: true in prod)
+- `boll_PROTOCOL_BYOK_SESSION_TTL_MINUTES` — BYOK session TTL
+- `boll_PROTOCOL_PUBLIC_ORIGIN` / `boll_PUBLIC_BASE_URL` / `boll_APP_PUBLIC_BASE_URL` — public URLs (note: `_build_public_run_url` only reads `app_public_base_url || public_base_url`; `protocol_public_origin` is reserved/unused as of 2026-04-07)
+- `RATE_LIMIT_OVERRIDES` — per-email rate limit overrides (`email:endpoint:max:window,...`); only effective for endpoints that pass `account_email` (not register/login)
+- `RATE_LIMIT_BYPASS_IPS` — comma-separated IP allowlist that skips ALL rate limiting; for internal E2E scripts and health checks running from localhost / known internal subnets so they don't burn the public per-IP register quota. Prod default: `127.0.0.1`
+- `boll_QUALITY_GATE_C_THRESHOLD` / `boll_QUALITY_GATE_A_THRESHOLD` — quality gate thresholds
+- `FIELD_SNAPSHOT_PATH` — field cache path
+- `RUN_TTL_ASSIGNED_MINUTES` / `RUN_TTL_RUNNING_MINUTES` / `RUN_TTL_DELIVERING_MINUTES` — run lifecycle TTLs
+- `RUN_MAX_RETRY_ATTEMPTS` / `RUN_RECOVERY_INTERVAL_SECONDS` — run recovery

package/src/bollharness/reference/boll-reference/.claude/rules/hackathon.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - "scenes/epic-hackathon/**"
+  - "backend/product/hackathon/**"
+  - "backend/product/routes/hackathon*.py"
+---
+
+# Hackathon 开发规则
+
+- 双字段模式：`_xxx_to_dict` 必须同时返回 `id` 和 `xxx_id`
+- ADR-037 场景适配器：协议概念不得泄露到场景 API，用 SceneAdapter 做翻译+编排+角色路由
+- 状态机：`backend/product/hackathon/state_machine.py` 是事件状态转换的单一真相源

package/src/bollharness/reference/boll-reference/.claude/rules/repo-structure.md

@@ -0,0 +1,184 @@
+---
+paths:
+  - "backend/**"
+  - "scenes/**"
+  - "website/**"
+  - "mcp-server/**"
+  - "mcp-server-node/**"
+  - "bridge_agent/**"
+  - "bridge_contract/**"
+  - "tests/**"
+  - "experiments/**"
+---
+
+# Repository Structure & Development Commands
+
+## Repository Structure
+
+```
+boll/
+├── CHANGELOG.md                     # Platform-level changelog (v0.1.0 ~ v0.4.1)
+├── backend/
+│   ├── server.py                    # V2-only FastAPI entry (port 8080)
+│   ├── boll/
+│   │   ├── __init__.py              # V2 field-only exports
+│   │   ├── field/                   # Intent Field module (12 files)
+│   │   └── matching/               # Discovery engine core (operators, recommendation, encoding, evaluation, logging)
+│   ├── product/                     # V2 productization layer
+│   │   ├── config.py                # Pydantic env-backed config
+│   │   ├── field_sync.py            # DB → MemoryField reload
+│   │   ├── llm.py                   # LLM client factory
+│   │   ├── quota.py                 # Commercial quota management
+│   │   ├── scheduler.py             # Run recovery scheduler
+│   │   ├── scene_chat_runtime.py    # SSE scene chat runtime
+│   │   ├── a2a/                     # A2A protocol adapter
+│   │   ├── auth/                    # Auth service + middleware + passwords + SecondMe OAuth
+│   │   ├── bridge/                  # Bridge protocol (local Mac ↔ cloud); event_translator.py: bridge→protocol 事件翻译层
+│   │   ├── catalyst/                # Cloud-side catalyst (coordinator, deadline scheduler, prompt loader); convergence.py: 收敛标记解析单一真相源
+│   │   ├── db/                      # SQLAlchemy engine + CRUD (users/demands/runs/events/artifacts)
+│   │   ├── demands/                 # Demand clarification-session + matching service
+│   │   ├── matching/               # Discovery pipeline (scanner, nominator, store)
+│   │   ├── inbox/                   # Inbox service
+│   │   ├── lanes/                   # Auth lanes (SecondMe AI etc.)
+│   │   ├── messaging/               # Inter-agent messaging
+│   │   ├── metrics/                 # Platform metrics calculator
+│   │   ├── notifications/           # SSE notification stream
+│   │   ├── coaching/                # Coaching service (kunzhi-coach prompts, export, constants)
+│   │   ├── hackathon/               # Hackathon service (state_machine, service layer)
+│   │   ├── openagents/              # OpenAgents runtime carrier + session manager
+│   │   ├── protocol/               # Canonical protocol API (bootstrap, deps, encoding, federation, service)
+│   │   ├── public_profiles/         # Public profile service
+│   │   ├── routes/                  # API routes (auth/profile/admin/demands/bridge/runs/dashboard/scene_auth/scene_chat/coaching/coaching_admin/hackathon/protocol/matching/a2a/plaza/public/public_profiles/did/messaging)
+│   │   ├── security/                # Security utilities (URL fetcher, sanitization)
+│   │   └── ws/                      # WebSocket hub + ticket auth
+│   ├── models/                      # ML model artifacts (bge-m3 embeddings)
+│   ├── tests/
+│   │   ├── field/                   # V2 field unit tests (89)
+│   │   ├── product/                 # Product unit tests (545, needs Docker)
+│   │   ├── unit/                    # Pure in-memory unit tests (60, no Docker)
+│   │   ├── matching/               # Discovery engine tests (21)
+│   │   └── test_phase0_surface.py   # Phase-0 surface gate tests (8)
+│   └── venv/
+├── bridge_contract/                 # Pure-Python bridge contract helpers (artifacts, events, finalization, runtime_profile)
+├── bridge_agent/                    # Local bridge agent (polls cloud → runs convergence)
+│   ├── agent.py                     # Bridge agent entry
+│   ├── bridge_listen.py             # HTTP helper (await-task, monitor, complete)
+│   ├── test_progress.py             # Progress detection tests (31)
+│   ├── config.yaml                  # Bridge config
+│   └── run_e2e.py                   # E2E test runner
+├── mcp-server/                      # MCP server — Python (boll-mcp, version see pyproject.toml)
+│   ├── boll_mcp/                   # 74 active tools (version see pyproject.toml)
+│   ├── CHANGELOG.md                 # MCP-specific changelog (0.3.0 ~ 0.4.0)
+│   └── pyproject.toml
+├── mcp-server-node/                 # MCP server — TypeScript/Node (boll-mcp, version see package.json)
+│   ├── src/                         # 74 active tools (mirror of Python version)
+│   └── package.json
+├── tests/
+│   ├── convergence_poc/         # Crystallization protocol experiments + tests (9)
+│   │   ├── prompts/                 # Prompt version chain
+│   │   └── simulations/real/        # RUN-001 ~ RUN-006
+│   └── field_poc/                   # Field experiment archive (EXP-005~008)
+├── website/
+│   ├── app/
+│   │   ├── page.tsx                 # Home
+│   │   ├── (auth)/                  # Login + Register pages
+│   │   ├── dashboard/               # User dashboard
+│   │   ├── demand/                  # New demand + match result
+│   │   ├── field/                   # Field experience page
+│   │   ├── profile/                 # User profile
+│   │   ├── run/                     # Run progress + result
+│   │   └── workspace/               # Startup Hub workspace
+│   └── package.json
+├── docs/
+│   ├── ARCHITECTURE_DESIGN.md       # V1 architecture (archived reference)
+│   ├── archive/ENGINEERING_REFERENCE.md  # Engineering standards (archived)
+│   ├── INDEX.md                     # Documentation navigation index
+│   ├── ROADMAP.md                   # Milestones + current direction + planned
+│   ├── architecture/                # Modular arch docs (principles, modules, vision)
+│   ├── community/                   # Profile contribution guide
+│   ├── decisions/                   # ADR + TECH + TEST + PLAN + REVIEW + EVAL
+│   │   ├── ADR-001~034              # Architecture Decision Records
+│   │   ├── TECH-015/TECH-018/TECH-SPEC-008  # Engineering designs
+│   │   ├── TEST-015/TEST-019        # Test designs
+│   │   ├── PLAN-001~080             # Implementation plans
+│   │   ├── REVIEW-015~057           # Audits
+│   │   └── tasks/                   # Task documents (use `find docs/decisions/tasks -name '*.md' | wc -l` to count)
+│   ├── issues/                      # Guardian/red-team issue documents (guard-YYYYMMDD-HHMM-*.md)
+│   ├── design-logs/                 # Design evolution logs (001~008)
+│   ├── research/                    # Research reports (000~015)
+│   ├── reviews/                     # Review artifacts (review-015, review-015-2)
+│   ├── guides/                      # Developer guides
+│   ├── archive/                     # Legacy V1 docs
+│   └── prompts/                     # V1 skill prompts (archived)
+├── scenes/                          # Scene demo apps
+│   ├── admin-dashboard/            # 管理后台 demo (Vite + React)
+│   ├── ai-gig-market/              # AI Agent 零工平台 demo (Vite + React)
+│   ├── craw-opc/                   # Craw OPC (placeholder)
+│   ├── epic-hackathon/             # Epic Hackathon demo (Vite + React)
+│   ├── hackathon-observer/         # Hackathon 观察者 (archive)
+│   ├── kunzhi-coach/               # example-coach scene app + prompts
+│   ├── kunzhi-coach-admin/         # example-coach后台管理 (Vite + React)
+│   ├── lobster-office/             # 龙虾办公 demo (Vite + React)
+│   ├── shrimp-hackathon/           # Shrimp Hackathon (placeholder)
+│   ├── smart-home-butler/          # 智能家居管家 (placeholder)
+│   └── startup-hub/                # Startup Hub workspace
+├── experiments/
+│   └── real_data/                   # Discovery GT Recall experiments (WP-015)
+├── scripts/                         # Utility scripts
+├── data/
+│   └── profiles/                    # Community profiles
+└── .claude/skills/                  # Repo-local Codex skills（见 docs/skills/REGISTRY.md）
+```
+
+## Development Commands
+
+```bash
+# Backend
+cd backend
+source venv/bin/activate
+uvicorn server:app --reload --port 8080
+
+# Deployment (MUST use this, never manual scp — hook enforced)
+bash scripts/deploy.sh --yes        # Full deploy: coherence check → sync → restart → verify
+bash scripts/deploy.sh --dry-run    # Preview only, no changes
+bash scripts/deploy-edge.sh --yes   # Sync repo-managed nginx edge config + verify public routes
+bash scripts/deploy-edge.sh --dry-run
+# Note: --yes skips interactive confirmation (required for AI execution)
+# Manual scp/rsync to production server is blocked by PreToolUse hook
+
+# Demo frontend deployment (static files, no backend restart)
+bash scripts/deploy-demo.sh ai-gig-market --channel prod --yes     # Build + deploy public demo
+bash scripts/deploy-demo.sh ai-gig-market --channel preview --yes  # Build + deploy internal preview
+bash scripts/deploy-demo.sh ai-gig-market --dry-run     # Preview only
+bash scripts/deploy-demo.sh ai-gig-market --skip-build --yes  # Deploy existing dist
+
+# Frontend
+cd website
+npm run dev
+
+# Tests (1992 collectable as of 2026-04-06)
+cd /Users/nature/个人项目/boll
+backend/venv/bin/pytest -q backend/tests/test_phase0_surface.py   # Phase-0 gate (8)
+backend/venv/bin/pytest -q backend/tests/field                     # Field unit (89)
+backend/venv/bin/pytest -q backend/tests/unit                      # Pure in-memory unit (462, no Docker)
+backend/venv/bin/pytest -q backend/tests/product                   # Product unit (750, needs Docker)
+backend/venv/bin/pytest -q backend/tests/matching                 # Discovery engine (21)
+backend/venv/bin/pytest -q tests/convergence_poc/simulations/real  # Crystallization (9)
+backend/venv/bin/pytest -q bridge_agent/test_progress.py           # Bridge progress (31)
+
+# MCP Server (Python)
+pip install -e ./mcp-server
+boll-mcp --help
+
+# MCP Server (Node/TypeScript)
+cd mcp-server-node
+npm install && npm run build
+npx boll-mcp
+
+# Official install entry
+/mcp
+
+# Frontend build
+cd website
+npm run build
+```