# DeepPane

DeepPane is an AI-callable ambient focus workspace and work-time dashboard for creating, sharing, and tracking focus spaces.

## Public agent docs

- Agent docs: https://deeppane.com/agents
- MCP quickstart: https://deeppane.com/mcp
- Dashboard: https://deeppane.com/dashboard/history
- Repository docs: docs/AGENT_FOCUS_SPACE_CREATION.md, docs/AGENT_AUTH_HANDOFF.md, docs/AGENT_WORK_TIME_HISTORY_API.md, docs/AGENT_MCP_WRAPPER_CONTRACT.md
- Production MCP access: use the Agent Key CTA on https://deeppane.com/agents when an integration needs registered attribution, bounded quota, abuse controls, and stable provenance. Public OAuth, marketplace, and agent pricing are separate future tracks.

## Callable agent abilities

1. Create a focus space
- Endpoint: POST /v1/agent/focus-spaces
- Anonymous/free behavior: public first-touch path; bounded custom timer, catalog quote, server-selected scene and optional music, share URL result, strict public limits, and a 25-minute web music preview ceiling.
- Registered agent-key behavior: production attribution path; send X-DeepPane-Agent-Key for app attribution, bounded agent quota, and stable agent provenance. It does not grant Pro behavior, user identity, history access, or media access.
- User-authorized behavior: use POST /v1/agent-auth/focus-space-create-token, then call POST /v1/agent/focus-spaces with Authorization: Bearer <agent-handoff-token>.
- Attribution behavior: send bounded attribution.agentRunId when available. Creation responses include conversion.installUrl and conversion.dashboardUrl for install/sign-in/history loops; these URLs may include safe UTM, dp_agent_id, and dp_agent_run_id parameters. conversion.installUrl routes through /agents/install so DeepPane can record a low-sensitive aggregate install-click event before redirecting to Chrome Web Store; attributed Dashboard openings record a low-sensitive aggregate landing event. Do not put secrets, emails, session ids, IPs, user agents, or raw prompt text in attribution fields.
- Scope: focus_space.create
- Use case: create a playable DeepPane link for a task, study sprint, writing session, recovery block, or ambient work period.

2. Read a work-time history summary
- Handoff endpoint: POST /v1/agent-auth/history-summary-token
- Summary endpoint: GET /v1/focus-logs/history-summary
- Scope: focus_logs.history_summary.read
- Authentication: user-authorized agent handoff token required for agents; anonymous, free-device, and share-token access must not return personal history.
- Use case: summarize recent work rhythm, explain weekly/monthly trends, recommend the next focus action, and prepare user-facing review notes.

## Security and privacy boundaries

- Creation responses return a DeepPane share URL, PNG/SVG QR code URLs, and compact selected metadata, not original media URLs, signed media URLs, R2 keys, storage buckets, internal scores, full tag graphs, or bulk catalog results.
- Conversion URLs and attribution fields are for low-sensitive funnel measurement only; they must not contain tokens, raw user identifiers, personal history, or media URLs. Run attribution is hash-bucketed before aggregate storage.
- History summary responses return compact summaries and markdown, not raw event rows, raw session ids, emails, IPs, user agents, notes, or per-event metadata.
- Handoff scopes are separate. focus_space.create cannot read history; focus_logs.history_summary.read cannot create spaces.
- Users can revoke currently minted short-lived handoff tokens from Dashboard Agent Access. Revoked handoff tokens fail closed and must be recreated through consent.
- Official MCP status: production-supported stdio server at apps/mcp-server/server.js with strict initialize lifecycle, inputSchema validation, outputSchema declarations, and structuredContent results.
- MCP servers should expose callable tools for these abilities only. Do not expose media-library browsing, bulk asset download, tag graph export, ranking weights, or signed media access.
- Recommended MCP tools: deeppane.create_focus_space, deeppane.request_focus_space_create_token, deeppane.request_history_summary_token, deeppane.read_history_summary.
- Forbidden MCP wrapper names include deeppane.list_scenes, deeppane.list_music, deeppane.search_media_catalog, deeppane.download_scene, deeppane.get_signed_media_url, deeppane.export_media_tags, and deeppane.export_raw_focus_events.

## Stable response fields

- Focus-space creation: ok, schemaVersion, shareUrl, shortShareUrl, longShareUrl, qrCodeUrl, qrCodePngUrl, qrCodeSvgUrl, shareId, expiresAt, policy, selected, conversion.
- History summary: schemaVersion, audience, purpose, window, metrics, periods, weeklyTrend, highlights, recommendations, markdown, generatedAt.

## Agent guidance

Create a DeepPane focus space when the user wants an actionable work session. Ask the user to authorize the correct handoff token before using Pro-only creation controls or reading personal work-time history. Prefer the history summary markdown field for short context. Do not treat DeepPane as a media catalog or bulk export service.
For production integrations, prefer a registered Agent Key plus a bounded agentRunId so DeepPane can attribute creation, share-page opening, install/dashboard paths, and history markers without broad OAuth or marketplace authorization.