diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index d5c7e8d0..879911e8 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -25,6 +25,6 @@ They may remove, edit, or reject comments, commits, issues, and pull requests th
 
 ## Reporting
 
-Until a dedicated security or community contact is published, open a private maintainer contact channel before sharing sensitive concerns publicly.
+To report a Code of Conduct violation, open a private maintainer contact or email the maintainers directly. Do not report conduct concerns as public GitHub issues.
 
-This document is intentionally short for the planning phase and can be expanded later.
\ No newline at end of file
+For security vulnerabilities, see [SECURITY.md](SECURITY.md).
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 30194df8..6a8cfd00 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,48 +2,54 @@
 
 Thanks for contributing to Paca.
 
-This repository is being documented before implementation, so the current priority is clarity of structure, product direction, and contributor expectations.
-
-## Current Focus
+## Repository Shape
 
-- Define a repository structure that is simple to navigate in public.
-- Document architecture and boundaries before writing production code.
-- Keep decisions reversible until implementation starts.
+- `apps/web` — React + TanStack Start + shadcn/ui frontend.
+- `apps/mcp` — MCP server (`@paca-ai/paca-mcp` npm package).
+- `apps/e2e` — Playwright end-to-end test suite.
+- `services/api` — Go + Gin application backend.
+- `services/realtime` — Node.js + Socket.IO real-time event fan-out.
+- `services/ai-agent` — Python + FastAPI + OpenHands SDK AI agent runtime.
+- `docs` — architecture, guides, API, deployment, and plugin documentation.
+- `deploy` — Docker Compose files and environment templates.
+- `plugins` — local plugin store (WASM + frontend bundles).
+- `scripts` — install and plugin management scripts.
 
-## Repository Shape
+## Development Setup
 
-- `apps/web`: the React + shadcn/ui frontend.
-- `services/api`: the Go + Gin application backend.
-- `services/ai-agent`: the FastAPI + LangGraph AI runtime.
-- `docs`: architecture, guides, product, API, and deployment notes.
-- `deploy`: local and future deployment assets.
+See [docs/guides/local-development.md](docs/guides/local-development.md) for a complete walkthrough of the local dev environment.
 
-## How to Contribute Right Now
+**Quick start:**
 
-- Improve documentation clarity.
-- Propose architecture decisions with clear tradeoffs.
-- Open issues for missing project structure, contributor workflow, or product concepts.
-- Avoid introducing implementation-heavy detail unless it is necessary for a foundational decision.
+```bash
+# Start infrastructure
+docker compose -f deploy/docker-compose.dev.yml up -d postgres valkey
 
-## Contribution Guidelines
+# Run the API
+cd services/api && make run
 
-- Keep pull requests focused.
-- Prefer documentation-first changes while the repository is still in planning.
-- Explain the reasoning behind structure changes.
-- Avoid premature abstraction in repo layout or service boundaries.
+# Run the web app
+cd apps/web && bun install && bun run dev
+```
 
-## Discussion Areas
+## Contribution Guidelines
 
-- Product workflow and user experience.
-- Service responsibilities and system boundaries.
-- Local development and deployment approach.
-- Open-source governance and contributor experience.
+- Keep pull requests focused on one concern.
+- Explain the reasoning behind non-obvious changes.
+- Update relevant docs when changing behavior or interfaces.
+- Avoid premature abstraction — add it when reuse is proven.
 
 ## Pull Request Checklist
 
 - The change is scoped to one concern.
-- Documentation stays consistent with the planned repository shape.
-- New decisions are explained clearly.
-- Related docs are updated when needed.
+- Tests are added or updated for changed behaviour.
+- Related documentation is updated.
+- New decisions or non-obvious tradeoffs are explained clearly.
+
+## Discussion Areas
 
-As the codebase becomes runnable, this document should expand to include setup, testing, and review workflow.
\ No newline at end of file
+- Product workflow and user experience.
+- Service responsibilities and system boundaries.
+- Plugin system design and extension points.
+- AI agent behaviour and collaboration model.
+- Open-source governance and contributor experience.
\ No newline at end of file
diff --git a/README.md b/README.md
index eb2d90dc..ff87cf82 100644
--- a/README.md
+++ b/README.md
@@ -276,10 +276,11 @@ For a complete reference and advanced configuration (agent-mode, plugin tools, p
 ## Architecture
 
 ```
-apps/web          React + shadcn/ui — user interface
+apps/web          React + TanStack Start + shadcn/ui — user interface
+apps/mcp          @paca-ai/paca-mcp — MCP server for AI agent integration
 services/api      Go + Gin — core business logic and REST API
-services/realtime Socket.IO — real-time event fan-out
-services/ai-agent FastAPI + OpenHands — AI agent orchestration (isolated sandbox container)
+services/realtime Node.js + Socket.IO — real-time event fan-out
+services/ai-agent Python + FastAPI + OpenHands SDK — AI agent orchestration
 apps/e2e          Playwright — end-to-end test suite
 
 PostgreSQL        Persistent store
@@ -305,10 +306,12 @@ But Paca is built from conviction: human-AI collaboration in a real Scrum team s
 | Document | Description |
 |:--|:--|
 | [docs/architecture/overview.md](docs/architecture/overview.md) | High-level system architecture |
+| [docs/guides/getting-started.md](docs/guides/getting-started.md) | Getting started (install, Docker, local dev) |
 | [docs/guides/local-development.md](docs/guides/local-development.md) | Contributor dev environment setup |
 | [docs/guides/mcp-server-setup.md](docs/guides/mcp-server-setup.md) | Connect AI agents via MCP |
 | [docs/plugins/](docs/plugins/) | Plugin system: backend (WASM) and frontend |
 | [deploy/README.md](deploy/README.md) | Full deployment reference |
+| [CHANGELOG.md](CHANGELOG.md) | Release history |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
 | [SECURITY.md](SECURITY.md) | Security policy |
 
diff --git a/SECURITY.md b/SECURITY.md
index 9fce66b3..4e69d678 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,30 +1,31 @@
 # Security Policy
 
-Paca is in an early documentation-first phase.
-
 ## Reporting a Vulnerability
 
-- Do not open public issues for security vulnerabilities.
-- Report vulnerabilities privately to the maintainers once a contact channel is published.
-- Include the affected area, impact, reproduction details, and any suggested mitigation.
+**Do not open public GitHub issues for security vulnerabilities.**
+
+To report a vulnerability privately:
+1. Open a [GitHub Security Advisory](https://github.com/Paca-AI/paca/security/advisories/new) in the repository.
+2. Include: the affected component, impact assessment, reproduction steps, and any suggested mitigation.
+
+We will acknowledge the report within 5 business days and aim to provide an initial assessment within 10 business days.
 
 ## Scope
 
 Security reports may cover:
 
-- authentication and authorization risks;
-- data exposure risks involving PostgreSQL, Redis, or message flows;
-- unsafe AI agent actions or privilege boundaries;
-- supply chain or dependency risks;
-- deployment misconfiguration risks.
+- Authentication and authorization risks.
+- Data exposure risks involving PostgreSQL, Valkey, or inter-service message flows.
+- Unsafe AI agent actions or privilege escalation.
+- WASM plugin sandbox escapes or capability bypasses.
+- Supply chain or dependency risks.
+- Deployment misconfiguration risks (Docker Compose, nginx, environment variables).
+- API injection risks (SQL injection, command injection, XSS).
 
-## Current Status
+## Supported Versions
 
-The project does not yet publish a formal response SLA.
+We address security issues in the latest released version. Older versions are not actively maintained for security patches.
 
-As implementation begins, this document should be updated with:
+## Disclosure
 
-- a reporting address;
-- supported versions;
-- disclosure expectations;
-- response timelines.
\ No newline at end of file
+We follow responsible disclosure: we ask that you give us reasonable time to patch a vulnerability before any public disclosure. We will credit reporters in release notes unless you prefer to remain anonymous.
diff --git a/apps/README.md b/apps/README.md
index 09c13f12..16a81b45 100644
--- a/apps/README.md
+++ b/apps/README.md
@@ -1,9 +1,11 @@
 # Apps
 
-This directory contains user-facing applications.
+This directory contains user-facing applications and their support tooling.
 
-## Planned App
+## Apps
 
-- `web`: the main React + shadcn/ui product interface.
+- `web` — the main React + TanStack Start + shadcn/ui product interface.
+- `mcp` — the `@paca-ai/paca-mcp` MCP server npm package.
+- `e2e` — Playwright end-to-end test suite.
 
-The app layer should stay focused on user experience and presentation concerns.
\ No newline at end of file
+The app layer stays focused on user experience, presentation concerns, and tooling that directly exercises the product surface.
diff --git a/apps/mcp/CHANGELOG.md b/apps/mcp/CHANGELOG.md
index 26b03460..8f204aa5 100644
--- a/apps/mcp/CHANGELOG.md
+++ b/apps/mcp/CHANGELOG.md
@@ -1,82 +1,82 @@
 # Changelog
 
-All notable changes to the Paca MCP server will be documented in this file.
+All notable changes to the Paca MCP server (`@paca-ai/paca-mcp`) will be documented in this file.
 
-## [0.1.0] - 2024-04-25
+The package version follows the main Paca repository release and is published on every new release.
+
+## [Unreleased]
+
+### Planned
+- Batch operations for bulk task updates
+- Pagination and filtering options for list tools
+- Search functionality across projects and tasks
+- Unit and integration test coverage
+
+---
+
+## [0.3.1] — 2026-06-05
+
+Full changelog: [github.com/Paca-AI/paca/releases/tag/v0.3.1](https://github.com/Paca-AI/paca/releases/tag/v0.3.1)
+
+No MCP-specific changes. Released in sync with the main repository.
+
+---
+
+## [0.3.0] — 2026-06-04
+
+Full changelog: [github.com/Paca-AI/paca/releases/tag/v0.3.0](https://github.com/Paca-AI/paca/releases/tag/v0.3.0)
+
+No MCP-specific changes. Released in sync with the main repository (AI agent integration).
+
+---
+
+## [0.2.0] — 2026-05-22
+
+Full changelog: [github.com/Paca-AI/paca/releases/tag/v0.2.0](https://github.com/Paca-AI/paca/releases/tag/v0.2.0)
 
 ### Added
-- Initial release of Paca MCP server
-- API key authentication support
-- Project management tools (5 tools)
-- Task management tools (6 tools)
-- Sprint management tools (6 tools)
-- Document management tools (5 tools)
-- Automatic BlockNote ↔ Markdown conversion
-- Modular architecture with clear separation of concerns
-- Comprehensive documentation (5 documentation files)
+- **Permission-based tool filtering** — tools are filtered at startup based on the authenticated user's or agent's permissions. Unauthorized tools are hidden rather than returning errors.
+- **Agent mode** — set `PACA_AGENT_ID` + `PACA_PROJECT_ID` to impersonate a project agent using the server's global `AGENT_API_KEY`.
+- **User single-project mode** — set `PACA_PROJECT_ID` without `PACA_AGENT_ID` to scope all tools to a single project.
+- **Project members** (5 tools): `list_project_members`, `add_project_member`, `get_my_project_permissions`, `update_project_member_role`, `remove_project_member`.
+- **Project roles** (4 tools): `list_project_roles`, `create_project_role`, `update_project_role`, `delete_project_role`.
+- **Task types** (5 tools): `list_task_types`, `create_task_type`, `update_task_type`, `delete_task_type`, `set_default_task_type`.
+- **Task statuses** (4 tools): `list_task_statuses`, `create_task_status`, `update_task_status`, `delete_task_status`.
+- **Views** (9 tools): `list_views`, `create_view`, `reorder_views`, `get_view`, `update_view`, `delete_view`, `list_task_positions`, `bulk_move_tasks`, `move_task`.
+- **Custom fields** (5 tools): `list_custom_fields`, `create_custom_field`, `get_custom_field`, `update_custom_field`, `delete_custom_field`.
+- **Attachments** (3 tools): `list_task_attachments`, `get_attachment_download_url`, `delete_task_attachment`.
+- **Document folders** (4 tools): `list_doc_folders`, `create_doc_folder`, `update_doc_folder`, `delete_doc_folder`.
+- **Document snapshots** (2 tools): `list_doc_snapshots`, `get_doc_snapshot`.
+- **GitHub integration** (7 tools): `get_github_integration`, `set_github_token`, `delete_github_token`, `list_github_repositories`, `list_linked_github_repos`, `link_github_repository`, `unlink_github_repository`.
+- **Task GitHub** (5 tools): `list_task_prs`, `link_pr_to_task`, `unlink_pr_from_task`, `create_branch_for_task`, `list_task_branches`.
+- **Task activities** (4 tools): `list_task_activities`, `add_task_comment`, `update_task_comment`, `delete_task_comment`.
+- **Plugin tools** — plugins that declare an `mcp.remoteEntryUrl` in their manifest are loaded dynamically at startup. Their tools appear alongside core tools with no distinction from the client's perspective.
 
 ### Changed
-- Refactored from monolithic 1,374-line file to modular 13-file structure
-- Separated concerns into 6 distinct layers (types, api, tools, utils, server, entry)
-- Improved code organization and maintainability
-- Enhanced type safety throughout
-
-### Structure
-```
-src/
-├── api/           # HTTP communication
-├── tools/         # MCP tool definitions
-├── types/         # TypeScript types
-├── utils/         # Utility functions
-├── server.ts      # MCP server setup
-└── index.ts       # Entry point
-```
-
-### Documentation
-- README.md - User documentation and quick start guide
-- DEVELOPMENT.md - Developer guide and contribution guidelines
-- IMPLEMENTATION.md - Technical implementation details
-- ARCHITECTURE.md - Architecture diagrams and design principles
-- REFACTORING_SUMMARY.md - Summary of refactoring changes
-
-### Features
-- **23 MCP tools** across 4 domains:
-  - Projects: list, get, create, update, delete
-  - Tasks: list, get, get-by-number, create, update, delete
-  - Sprints: list, get, create, update, delete, complete
-  - Documents: list, get, create, update, delete
-
-- **BlockNote Integration**:
-  - Automatic conversion from Markdown to BlockNote when writing
-  - Automatic conversion from BlockNote to Markdown when reading
-  - Supports rich text formatting in task descriptions and document content
-
-- **API Key Authentication**:
-  - Secure authentication via `X-API-Key` header
-  - Configuration via `PACA_API_KEY` environment variable
-  - Compatible with Paca's API key system
-
-### Technical Details
-- TypeScript for full type safety
-- Node.js stdio transport for MCP protocol
-- `@modelcontextprotocol/sdk` for MCP implementation
-- `@blocknote/core` for format conversion
-- `node-fetch` for HTTP requests
-- 1,623 lines of well-organized code
-- ~3,800 lines of comprehensive documentation
-
-### Configuration
-```bash
-PACA_API_KEY="your-api-key-here"        # Required
-PACA_API_URL="http://localhost:8080"    # Optional (default: http://localhost:8080)
-```
+- Total tool count: **23 → 81 tools** across **16 categories**.
+- Task detail enriched with additional fields (story points, parent task, tags, custom fields).
 
-## [Unreleased]
+---
+
+## [0.1.1] — 2026-04-28
+
+Full changelog: [github.com/Paca-AI/paca/releases/tag/v0.1.1](https://github.com/Paca-AI/paca/releases/tag/v0.1.1)
 
-### Planned Features
-- Additional API endpoints (attachments, notifications, views, etc.)
-- Batch operations
-- Filtering and pagination
-- Search functionality
-- Real-time updates via WebSockets
-- Unit and integration tests
+### Fixed
+- Project tool descriptions clarified to specify that `projectId` parameters expect a UUID, not a project name.
+
+---
+
+## [0.1.0] — 2026-04-28
+
+Full changelog: [github.com/Paca-AI/paca/releases/tag/v0.1.0](https://github.com/Paca-AI/paca/releases/tag/v0.1.0)
+
+### Added
+- Initial release of `@paca-ai/paca-mcp`.
+- API key authentication via `X-API-Key` header (`PACA_API_KEY` environment variable).
+- **Project management** (5 tools): `list_projects`, `get_project`, `create_project`, `update_project`, `delete_project`.
+- **Task management** (6 tools): `list_tasks`, `get_task`, `get_task_by_number`, `create_task`, `update_task`, `delete_task`.
+- **Sprint management** (6 tools): `list_sprints`, `get_sprint`, `create_sprint`, `update_sprint`, `delete_sprint`, `complete_sprint`.
+- **Document management** (5 tools): `list_documents`, `get_document`, `create_document`, `update_document`, `delete_document`.
+- Automatic BlockNote ↔ Markdown conversion for task descriptions and document content.
+- Modular architecture: `types`, `api`, `tools`, `utils`, `server`, `index` layers.
diff --git a/docs/ai-agent/api-design.md b/docs/ai-agent/api-design.md
index 943531fa..bc96a2f9 100644
--- a/docs/ai-agent/api-design.md
+++ b/docs/ai-agent/api-design.md
@@ -26,7 +26,7 @@ List all agents in a project.
       "slug": "developer"
     },
     "llm_provider": "anthropic",
-    "llm_model": "claude-sonnet-4-5-20250929",
+    "llm_model": "claude-sonnet-4-6",
     "can_clone_repos": true,
     "can_create_prs": true,
     "max_iterations": 50,
@@ -50,7 +50,7 @@ Create a new agent. This also creates the corresponding `project_members` row wi
   "handle": "dev-bot",
   "agent_type_id": "uuid",
   "llm_provider": "anthropic",
-  "llm_model": "claude-sonnet-4-5-20250929",
+  "llm_model": "claude-sonnet-4-6",
   "llm_api_key": "sk-ant-...",
   "llm_base_url": null,
   "system_prompt": "You are a senior software engineer...",
diff --git a/docs/ai-agent/database-schema.md b/docs/ai-agent/database-schema.md
index 41184066..c3232b0f 100644
--- a/docs/ai-agent/database-schema.md
+++ b/docs/ai-agent/database-schema.md
@@ -22,7 +22,7 @@ Table agent_types {
   description text [not null, default: '']
   slug varchar [not null, note: 'Machine-readable identifier: po-assistant | ba | developer | manual-tester | custom']
   default_llm_provider varchar [not null, note: 'LiteLLM provider prefix, e.g. anthropic, openai, azure']
-  default_llm_model varchar [not null, note: 'LiteLLM model name, e.g. claude-sonnet-4-5-20250929']
+  default_llm_model varchar [not null, note: 'LiteLLM model name, e.g. claude-sonnet-4-6']
   default_system_prompt text [not null, default: '']
   is_builtin boolean [not null, default: false]
   created_at timestamp [not null]
diff --git a/docs/ai-agent/overview.md b/docs/ai-agent/overview.md
index 4be7fed9..1c20a383 100644
--- a/docs/ai-agent/overview.md
+++ b/docs/ai-agent/overview.md
@@ -212,10 +212,10 @@ This design means:
 
 | Type | Role | Default LLM | Pre-loaded Skills |
 |---|---|---|---|
-| **PO Assistant** | Product Owner — backlog grooming, acceptance criteria, prioritization | `anthropic/claude-sonnet-4-5` | `po-assistant` skill with Agile PO guidelines |
-| **Business Analyst** | Requirements analysis, user story writing, gap analysis | `anthropic/claude-sonnet-4-5` | `ba-assistant` skill |
-| **Developer** | Coding, code review, PR creation, bug fixing | `anthropic/claude-sonnet-4-5` | `developer` skill + `github`/`gitlab` skills |
-| **Manual Tester** | Test case design, exploratory testing docs, defect analysis | `anthropic/claude-sonnet-4-5` | `manual-tester` skill |
+| **PO Assistant** | Product Owner — backlog grooming, acceptance criteria, prioritization | `anthropic/claude-sonnet-4-6` | `po-assistant` skill with Agile PO guidelines |
+| **Business Analyst** | Requirements analysis, user story writing, gap analysis | `anthropic/claude-sonnet-4-6` | `ba-assistant` skill |
+| **Developer** | Coding, code review, PR creation, bug fixing | `anthropic/claude-sonnet-4-6` | `developer` skill + `github`/`gitlab` skills |
+| **Manual Tester** | Test case design, exploratory testing docs, defect analysis | `anthropic/claude-sonnet-4-6` | `manual-tester` skill |
 
 Users can create custom agent types with any combination of LLM provider, skills, MCP servers, and system prompt.
 
diff --git a/docs/api/http-design.md b/docs/api/http-design.md
index b8d23556..dbeba503 100644
--- a/docs/api/http-design.md
+++ b/docs/api/http-design.md
@@ -1630,7 +1630,8 @@ To keep the API coherent and aligned with the current codebase, implement the ne
 8. ~~Add sprint saved views: board, table, roadmap with manual task ordering.~~ ✅ Done
 9. Add task sub-resource endpoints: child tasks, activities, and time logs.
 10. ~~Add custom field definitions.~~ ✅ Done
-11. Add knowledge and reporting: documents and dashboards.
+11. ~~Add documents (CRUD, folders, snapshots, activities).~~ ✅ Done
+12. Add dashboards (planned).
 
 ## Known Model Gaps
 
diff --git a/docs/architecture/database-schema.md b/docs/architecture/database-schema.md
index 484dde01..7fa5bfca 100644
--- a/docs/architecture/database-schema.md
+++ b/docs/architecture/database-schema.md
@@ -8,13 +8,14 @@ Interactive diagram: [https://dbdiagram.io/d/Paca-69c212ae78c6c4bc7a4fc190](http
 
 | File | Purpose |
 |---|---|
-| `000001_init.sql` | Full consolidated schema: `global_roles`, `users`, projects (with `task_id_prefix` for human-readable task IDs), project roles/members, task configuration (`task_types`, `task_statuses`), `sprints`, `sprint_views` (with `view_context` field), `view_task_positions`, `custom_field_definitions`, `task_counters` (tracks per-project sequential task numbers), `tasks` (with `story_points`), `files` (central file-metadata registry), `task_attachments` (now links to `files` table), `task_activities`, `doc_folders` (hierarchical folders with `parent_id` self-reference, `position`, `created_by`), `documents` (BlockNote `content` JSONB, `folder_id`, `position`, soft-delete via `deleted_at`, `created_by`/`updated_by` referencing `project_members`), `doc_snapshots` (point-in-time content copies for diff/history, `snapshot_number` auto-incremented per document via a trigger), `doc_activities` (audit log + comments), `notifications` (task-assignment and @mention notifications with `recipient_user_id`, `actor_member_id`, `type`, `read_at`), `api_keys` (user API keys for programmatic authentication), `plugins` (core plugin registry), `plugin_extension_settings` (system-wide plugin extension point configuration), and seed data. Note: `task_checklists` and `task_checklist_items` tables were originally here but have been migrated to the `com.paca.checklist` plugin via migration 000005. |
-| `000002_add_story_points.sql` | Adds `story_points` INTEGER column to the tasks table (nullable, >= 0). |
-| `000003_add_project_is_public.sql` | Adds `is_public` BOOLEAN flag to projects table for anonymous read access. |
+| `000001_init.sql` | Full consolidated baseline schema (v0.1.x): `global_roles`, `users`, `projects` (with `task_id_prefix`), `project_roles`, `project_members`, `task_types`, `task_statuses`, `sprints`, `sprint_views` (with `view_context`), `view_task_positions`, `custom_field_definitions`, `task_counters`, `tasks`, `files`, `task_attachments`, `task_activities`, `doc_folders`, `documents`, `doc_snapshots`, `doc_activities`, `notifications`, `api_keys`, `plugins`, `plugin_extension_settings`, and seed data. |
+| `000002_add_story_points.sql` | Adds `story_points INTEGER` (nullable, >= 0) to `tasks`. |
+| `000003_add_project_is_public.sql` | Adds `is_public BOOLEAN` to `projects` for anonymous read access. |
 | `000004_add_plugins.sql` | Adds `plugins` and `plugin_extension_settings` tables for the plugin system. |
-| `000005_migrate_checklists_to_plugin.sql` | Removes legacy `task_checklists` and `task_checklist_items` tables from public schema (migrated to com.paca.checklist plugin). |
-| `000006_add_plugin_view_type.sql` | Extends sprint_views.view_type CHECK constraint to allow 'plugin' as a valid view type. |
-| `000007_remove_github_tables.sql` | Removes GitHub integration tables (`github_integrations`, `github_repositories`, `github_pull_requests`, `github_task_pr_links`, `github_task_branches`) as they have been migrated to plugins. |
+| `000005_migrate_checklists_to_plugin.sql` | Drops legacy `task_checklists` and `task_checklist_items` tables (moved to `com.paca.checklist` plugin). |
+| `000006_add_plugin_view_type.sql` | Extends `sprint_views.view_type` CHECK to allow `'plugin'` as a valid view type. |
+| `000007_remove_github_tables.sql` | Drops GitHub integration tables (`github_integrations`, `github_repositories`, `github_pull_requests`, `github_task_pr_links`, `github_task_branches`) — migrated to plugins. |
+| `000008_add_ai_agents.sql` | Adds AI agent tables: `agents`, `agent_mcp_servers`, `agent_skills`, `agent_chat_sessions`, `agent_conversations`, `agent_conversation_events`. Modifies `project_members` to add `member_type` and `agent_id` (makes `user_id` nullable) for agent membership support. |
 
 ## Schema (DBML)
 
@@ -62,13 +63,16 @@ Table project_roles {
 Table project_members {
   id uuid [primary key]
   project_id uuid [ref: > projects.id]
-  user_id uuid [ref: > users.id]
+  user_id uuid [null, ref: > users.id, note: 'null for agent members']
   project_role_id uuid [ref: > project_roles.id]
+  member_type varchar [not null, default: 'human', note: 'human | agent']
+  agent_id uuid [null, ref: > agents.id, note: 'null for human members']
   created_at timestamp [not null]
-  deleted_at timestamp [null, note: 'Soft-delete timestamp. Non-null rows are excluded from active-member queries. Re-adding a removed member restores the existing row (sets deleted_at = NULL) rather than inserting a new one.']
+  deleted_at timestamp [null, note: 'Soft-delete timestamp. Re-adding a removed member restores the row rather than inserting a new one.']
 
   indexes {
-    (project_id, user_id) [unique, note: 'Partial unique index: WHERE deleted_at IS NULL']
+    (project_id, user_id) [unique, note: 'Partial unique: WHERE deleted_at IS NULL AND member_type = human']
+    (project_id, agent_id) [unique, note: 'Partial unique: WHERE deleted_at IS NULL AND member_type = agent']
   }
 }
 
@@ -200,17 +204,6 @@ Table view_task_positions {
   }
 }
 
-// --- FEATURES & UTILITIES ---
-// Note: task_checklists and task_checklist_items are owned by the com.paca.checklist plugin.
-
-Table time_logs {
-  id uuid [primary key]
-  task_id uuid [ref: > tasks.id]
-  member_id uuid [ref: > project_members.id]
-  duration_minutes integer
-  logged_date date
-}
-
 // --- FILES ---
 Table files {
   id uuid [primary key]
@@ -285,13 +278,6 @@ Table doc_activities {
   deleted_at    timestamp [null, note: 'Soft-delete for comments']
 }
 
-Table dashboards {
-  id uuid [primary key]
-  project_id uuid [ref: > projects.id]
-  name varchar
-  layout jsonb
-}
-
 Table task_activities {
   id uuid [primary key]
   task_id uuid [not null, ref: > tasks.id]
@@ -350,4 +336,118 @@ Table api_keys {
   created_at timestamp
   revoked_at timestamp [null]
 }
+
+// --- AI AGENTS (000008) ---
+
+Table agents {
+  id uuid [primary key]
+  project_id uuid [not null, ref: > projects.id]
+  name varchar [not null]
+  handle varchar [not null, note: '@mention handle, unique per project']
+  avatar_url varchar [null]
+  llm_provider varchar [not null, note: 'LiteLLM provider prefix, e.g. anthropic, openai']
+  llm_model varchar [not null, note: 'LiteLLM model name, e.g. claude-sonnet-4-6']
+  llm_api_key_secret varchar [not null, note: 'Encrypted at rest; never returned by the API']
+  llm_base_url varchar [null]
+  system_prompt text [not null, default: '']
+  can_clone_repos boolean [not null, default: true]
+  can_create_prs boolean [not null, default: true]
+  max_iterations integer [not null, default: 50]
+  timeout_minutes integer [not null, default: 30]
+  git_committer_name varchar [not null, default: 'paca-agent']
+  git_committer_email varchar [not null]
+  created_by uuid [null, ref: > users.id]
+  created_at timestamp
+  updated_at timestamp
+  deleted_at timestamp [null]
+
+  indexes {
+    (project_id, handle) [unique, note: 'Partial unique: WHERE deleted_at IS NULL']
+  }
+}
+
+Table agent_mcp_servers {
+  id uuid [primary key]
+  agent_id uuid [not null, ref: > agents.id]
+  server_name varchar [not null, note: 'Key in mcpServers map']
+  transport varchar [not null, note: 'stdio | sse | http | oauth']
+  command varchar [null]
+  args jsonb [not null, default: '[]']
+  url varchar [null]
+  env jsonb [not null, default: '{}']
+  is_enabled boolean [not null, default: true]
+  created_at timestamp
+  updated_at timestamp
+
+  indexes {
+    (agent_id, server_name) [unique]
+  }
+}
+
+Table agent_skills {
+  id uuid [primary key]
+  agent_id uuid [not null, ref: > agents.id]
+  skill_name varchar [not null]
+  skill_source varchar [not null, note: 'inline | marketplace | github_url']
+  skill_content text [not null, default: '']
+  source_url varchar [null]
+  triggers jsonb [not null, default: '[]']
+  is_enabled boolean [not null, default: true]
+  created_at timestamp
+  updated_at timestamp
+
+  indexes {
+    (agent_id, skill_name) [unique]
+  }
+}
+
+Table agent_chat_sessions {
+  id uuid [primary key]
+  agent_id uuid [not null, ref: > agents.id]
+  project_id uuid [not null, ref: > projects.id]
+  member_id uuid [not null, ref: > project_members.id, note: 'The human member chatting with the agent']
+  title varchar [null]
+  last_message_at timestamp [null]
+  created_at timestamp
+  updated_at timestamp
+}
+
+Table agent_conversations {
+  id uuid [primary key, note: 'Also used as the OpenHands conversation_id']
+  agent_id uuid [not null, ref: > agents.id]
+  project_id uuid [not null, ref: > projects.id]
+  trigger_type varchar [not null, note: 'task_assigned | comment_mention | chat_message']
+  task_id uuid [null, ref: > tasks.id]
+  comment_id uuid [null]
+  chat_session_id uuid [null, ref: > agent_chat_sessions.id]
+  triggered_by_member_id uuid [not null, ref: > project_members.id]
+  status varchar [not null, default: 'queued', note: 'queued | running | paused | finished | failed | stopped']
+  container_id varchar [null]
+  host_port integer [null]
+  iteration_count integer [not null, default: 0]
+  error_message text [null]
+  repo_plugin_id uuid [null]
+  repo_clone_url varchar [null]
+  branch_name varchar [null]
+  pr_url varchar [null]
+  persistence_dir varchar [null]
+  started_at timestamp [null]
+  finished_at timestamp [null]
+  created_at timestamp
+  updated_at timestamp
+}
+
+Table agent_conversation_events {
+  id uuid [primary key]
+  conversation_id uuid [not null, ref: > agent_conversations.id]
+  event_index integer [not null, note: 'Sequential index within the conversation (0-based)']
+  event_type varchar [not null, note: 'OpenHands SDK event type: MessageAction, CmdRunAction, FileEditAction, etc.']
+  event_source varchar [not null, note: 'agent | user | system | environment']
+  payload jsonb [not null, default: '{}']
+  created_at timestamp
+
+  indexes {
+    (conversation_id, event_index) [unique]
+  }
+}
 ```
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
index c9fafd57..33945c4f 100644
--- a/docs/architecture/overview.md
+++ b/docs/architecture/overview.md
@@ -1,14 +1,15 @@
 # Architecture Overview
 
-Paca is planned as a single open-source monorepo with a small set of clearly separated runtime surfaces.
+Paca is a single open-source monorepo with a small set of clearly separated runtime surfaces.
 
 ## Runtime Areas
 
-- `apps/web`: the user-facing application built with React and shadcn/ui.
-- `apps/e2e`: the end-to-end test suite built with Playwright; not a deployed runtime, but an external verifier of the full stack.
-- `services/api`: the main application backend built with Go and Gin.
-- `services/realtime`: the real-time delivery service built with Socket.IO.
-- `services/ai-agent`: the AI orchestration runtime built with FastAPI and LangGraph.
+- `apps/web` — the user-facing application built with React, TanStack Start, and shadcn/ui.
+- `apps/mcp` — the `@paca-ai/paca-mcp` MCP server; connects AI agents to the Paca data layer.
+- `apps/e2e` — the end-to-end test suite built with Playwright; not a deployed runtime, but an external verifier of the full stack.
+- `services/api` — the main application backend built with Go and Gin.
+- `services/realtime` — the real-time delivery service built with Node.js and Socket.IO.
+- `services/ai-agent` — the AI agent orchestration runtime built with Python, FastAPI, and the OpenHands SDK.
 
 ## Platform Dependencies
 
@@ -19,10 +20,11 @@ Paca is planned as a single open-source monorepo with a small set of clearly sep
 
 - `apps/web` uses HTTP APIs exposed by `services/api` for request-response workflows.
 - `apps/web` connects to `services/realtime` over Socket.IO for live updates.
+- `apps/mcp` calls `services/api` over HTTP using an API key; plugin tools route to `/api/v1/plugins/{pluginId}/…`.
 - `apps/e2e` drives a real browser against the full running stack and validates cross-cutting flows that span multiple runtime surfaces.
 - `services/api` remains the system of record for product state and publishes real-time relevant domain events to a Valkey Stream.
 - `services/realtime` consumes Valkey Stream messages from `services/api` and fans out client-safe events to connected Socket.IO rooms and users.
-- `services/ai-agent` integrates with the core backend and should publish or consume asynchronous events through explicit contracts rather than direct coupling.
+- `services/ai-agent` reads agent trigger events from a Valkey Stream, spawns Docker containers for each conversation via the OpenHands SDK, and publishes conversation events back to Valkey.
 
 ## Architectural Intent
 
@@ -33,6 +35,4 @@ Paca is planned as a single open-source monorepo with a small set of clearly sep
 - Separate product-facing documentation from implementation-facing documentation.
 - Keep the repository easy to read in public from the root.
 
-This document is intentionally high level. More detailed decisions should be added only when implementation forces them.
-
-For the shared sprint, backlog, and timeline view model, see [interaction-views.md](interaction-views.md).
\ No newline at end of file
+For the shared sprint, backlog, and timeline view model, see [interaction-views.md](interaction-views.md).
diff --git a/docs/architecture/repository-structure.md b/docs/architecture/repository-structure.md
index 6c57c3ef..250c187a 100644
--- a/docs/architecture/repository-structure.md
+++ b/docs/architecture/repository-structure.md
@@ -1,6 +1,6 @@
 # Repository Structure
 
-Paca starts with a documentation-first monorepo layout.
+Paca is a monorepo with clearly separated runtime surfaces, tooling, and documentation.
 
 ```text
 paca/
@@ -9,33 +9,35 @@ paca/
 ├── CODE_OF_CONDUCT.md
 ├── SECURITY.md
 ├── ROADMAP.md
-├── .github/
-├── docs/
+├── LICENSE
+├── .github/                    # CI workflows and issue templates
+├── docs/                       # Architecture, guides, API, and plugin documentation
 ├── apps/
-│   ├── web/
-│   └── e2e/
+│   ├── web/                    # React + TanStack Start + shadcn/ui frontend
+│   ├── mcp/                    # @paca-ai/paca-mcp MCP server (npm package)
+│   └── e2e/                    # Playwright end-to-end test suite
 ├── services/
-│   ├── api/
-│   ├── realtime/
-│   └── ai-agent/
+│   ├── api/                    # Go + Gin application backend
+│   ├── realtime/               # Node.js + Socket.IO real-time fan-out
+│   └── ai-agent/               # Python + FastAPI + OpenHands SDK agent runtime
+├── plugins/
+│   └── local/                  # Local plugin store (WASM binaries + frontend bundles)
+├── scripts/                    # Install and plugin management scripts
 └── deploy/
-    └── nginx/
+    ├── docker-compose.dev.yml
+    ├── docker-compose.prod.yml
+    ├── docker-compose.e2e.yml
+    └── nginx/                  # Gateway configuration mounted into nginx container
 ```
 
 ## Why This Shape
 
 - `docs` keeps durable technical writing out of the root.
-- `apps` holds user-facing surfaces and their test counterparts.
+- `apps` holds user-facing surfaces, the MCP integration, and their test counterparts.
 - `apps/e2e` lives under `apps` because it directly exercises `apps/web` and is versioned alongside it; it is not deployed.
 - `services` holds backend runtimes with different language stacks.
 - `services/realtime` is split out so Socket.IO delivery can scale and evolve independently from the transactional API.
-- `deploy` keeps environment and infrastructure assets in one place.
+- `plugins/local` is the on-disk plugin store — WASM modules and frontend bundles land here after installation.
+- `scripts` holds the install script and plugin management helpers used by the CLI and the Marketplace UI.
+- `deploy` keeps all environment and infrastructure assets in one place.
 - `deploy/nginx` holds gateway configuration that is mounted read-only into the nginx container at runtime, making it easy to review and modify without rebuilding images.
-
-## What Is Intentionally Missing
-
-- `packages` is deferred until shared code actually appears.
-- `scripts` is deferred until recurring automation exists.
-- `examples` is deferred because this repository is an application, not a library.
-
-The goal is to keep the public repository easy to scan while leaving room to grow.
\ No newline at end of file
diff --git a/docs/architecture/service-boundaries.md b/docs/architecture/service-boundaries.md
index 6518dc0e..a83d6e1c 100644
--- a/docs/architecture/service-boundaries.md
+++ b/docs/architecture/service-boundaries.md
@@ -1,17 +1,30 @@
 # Service Boundaries
 
-Paca is planned around one frontend application and three backend services.
+Paca consists of one frontend application, an MCP server, and three backend services.
 
 ## apps/web
 
 Responsible for the user-facing product experience.
 
-Planned concerns:
+Concerns:
 
 - authentication and session-driven UI flow;
-- board and task management interfaces;
-- human and AI collaboration views;
-- product-facing components built with React and shadcn/ui.
+- board, backlog, and sprint management interfaces;
+- human and AI agent collaboration views;
+- real-time board updates via Socket.IO;
+- product-facing components built with React, TanStack Start, and shadcn/ui.
+
+## apps/mcp
+
+Responsible for AI agent integration via the Model Context Protocol.
+
+Concerns:
+
+- MCP server implementation (`@paca-ai/paca-mcp` npm package);
+- translating MCP tool calls into REST calls to `services/api`;
+- permission-based tool filtering (user mode and agent mode);
+- dynamic loading of plugin-contributed MCP tools at startup;
+- BlockNote ↔ Markdown format conversion for descriptions and documents.
 
 ## apps/e2e
 
@@ -19,48 +32,52 @@ Responsible for end-to-end validation of the full running stack from a real brow
 
 Concerns:
 
-- Playwright test suites that exercise cross-cutting flows spanning `apps/web`, `services/api`, and the nginx gateway;
+- Playwright test suites exercising cross-cutting flows spanning `apps/web`, `services/api`, and the nginx gateway;
 - test categories: auth flows, form validation, security (injection/XSS rejection), session management, and UX correctness;
 - Page Object Models and shared fixtures to keep test logic stable as the UI evolves;
-- global setup that logs in once and persists browser auth state, giving session tests a pre-authenticated context without repeating login steps.
+- global setup that logs in once and persists browser auth state.
 
-Not deployed. Runs against a live environment (local stack or CI-provisioned stack) and produces an HTML report with traces and screenshots on failure.
+Not deployed. Runs against a live environment (local or CI stack) and produces an HTML report with traces and screenshots on failure.
 
 ## services/api
 
 Responsible for the core application backend.
 
-Planned concerns:
+Concerns:
 
-- business workflows;
-- task, board, and activity APIs;
-- persistence coordination with PostgreSQL and Redis;
-- publication of domain events to a Valkey Stream for downstream consumers, including the real-time service;
-- consumption of asynchronous events where API-owned workflows require it.
+- business workflows (tasks, sprints, boards, members, documents, custom fields);
+- authentication and authorization (JWT, API keys, role-based permissions);
+- persistence coordination with PostgreSQL and Valkey;
+- S3-compatible file attachment handling (MinIO or AWS S3);
+- WASM plugin runtime (wazero) — loads backend plugins, registers routes, mediates host function calls;
+- publication of domain events to Valkey Streams for downstream consumers;
+- agent trigger event publication and conversation summary ingestion.
 
 ## services/realtime
 
 Responsible for real-time delivery to connected clients.
 
-Planned concerns:
+Concerns:
 
-- maintain Socket.IO namespaces, rooms, and client connection lifecycle;
-- authenticate and authorize socket connections using contracts owned by the core backend;
-- consume Valkey Stream messages emitted by `services/api`;
-- transform internal domain events into client-safe real-time payloads;
-- broadcast updates for boards, tasks, comments, and presence-like collaboration signals.
+- Socket.IO namespaces, rooms, and client connection lifecycle;
+- authentication and authorization of socket connections using contracts from `services/api`;
+- consumption of Valkey Stream messages emitted by `services/api`;
+- transformation of internal domain events into client-safe real-time payloads;
+- broadcast of updates for boards, tasks, comments, agent conversation events, and collaboration signals.
 
 ## services/ai-agent
 
-Responsible for AI orchestration and agent execution.
+Responsible for AI agent orchestration and execution.
 
-Planned concerns:
+Concerns:
 
-- agent workflow execution with LangGraph;
-- API endpoints for AI-driven actions;
-- coordination with the core backend;
-- controlled access to runtime context and tools.
+- consumption of agent trigger events from the `paca:agent:triggers` Valkey Stream;
+- spawning and managing Docker containers via the OpenHands SDK (one container per active conversation);
+- running OpenHands agent conversations with per-agent LLM, skills, MCP servers, and system prompt config;
+- publishing conversation events to the `paca:agent:events` Valkey Stream for real-time delivery;
+- REST endpoints for pause, resume, stop, and history operations;
+- repository access via the repository plugin adapter (short-lived tokens, no persistent credential storage).
 
 ## Boundary Rule
 
-Keep ownership clear. `services/api` owns business rules and durable state transitions, while `services/realtime` only delivers live updates derived from API-owned events. Shared code should stay inside the owning runtime until duplication is real.
\ No newline at end of file
+Keep ownership clear. `services/api` owns business rules and durable state transitions. `services/realtime` only delivers live updates derived from API-owned events. `services/ai-agent` executes agent conversations and reports results back through `services/api` — it does not write directly to the database. Shared code stays inside the owning runtime until duplication is real and proven.
diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
index a3ae25b2..9cbd32bf 100644
--- a/docs/guides/getting-started.md
+++ b/docs/guides/getting-started.md
@@ -1,20 +1,95 @@
 # Getting Started
 
-Paca is currently in a documentation-first phase.
+## Option 1 — Install Script (recommended)
 
-## What to Read First
+Runs on any Linux server with Docker. Downloads the release assets, walks you through configuration interactively, and starts the full stack.
 
-1. Start with the root [README.md](../../README.md).
-2. Read [../architecture/overview.md](../architecture/overview.md).
-3. Read [../architecture/repository-structure.md](../architecture/repository-structure.md).
-4. Review [../../CONTRIBUTING.md](../../CONTRIBUTING.md).
+```bash
+curl -fsSL https://github.com/Paca-AI/paca/releases/latest/download/install.sh | bash
+```
 
-## Current State
+Open `http://your-server-ip` when it finishes.
 
-- The repository defines direction before implementation.
-- The monorepo structure is planned but not fully scaffolded.
-- Technical detail is intentionally limited until the first implementation pass starts.
+---
 
-## Near-Term Goal
+## Option 2 — Docker Compose (manual)
 
-The next milestone is to turn the documentation structure into minimal runnable scaffolding for the frontend, backend, and AI runtime.
\ No newline at end of file
+Pulls pre-built images. No repository clone required.
+
+```bash
+# Download compose file and nginx config
+mkdir paca && cd paca
+curl -fsSL https://github.com/Paca-AI/paca/releases/latest/download/docker-compose.yml -o docker-compose.yml
+mkdir -p nginx
+curl -fsSL https://github.com/Paca-AI/paca/releases/latest/download/gateway.conf -o nginx/gateway.conf
+
+# Create an environment file
+cat > .env <<'EOF'
+JWT_SECRET=<run: openssl rand -hex 32>
+ADMIN_PASSWORD=<your-admin-password>
+POSTGRES_PASSWORD=<run: openssl rand -hex 32>
+AGENT_API_KEY=<run: openssl rand -hex 32>
+INTERNAL_API_KEY=<run: openssl rand -hex 32>
+ENCRYPTION_KEY=<run: openssl rand -hex 32>
+PUBLIC_URL=http://localhost
+EOF
+
+# Start the stack
+docker compose --env-file .env up -d
+```
+
+Open `http://localhost` — log in with `admin` and the password you set.
+
+---
+
+## Option 3 — Local Development
+
+For contributors. Clone the repo, then start everything with one command:
+
+```bash
+git clone https://github.com/Paca-AI/paca.git && cd paca
+docker compose -f deploy/docker-compose.dev.yml up -d
+```
+
+All services start with hot-reload — the API, web app, and realtime service all watch your local source files and rebuild automatically. Open `http://localhost` when the stack is healthy.
+
+See [local-development.md](local-development.md) for details on the dev stack and running services on the host.
+
+---
+
+## Connect an AI Agent via MCP
+
+After Paca is running:
+
+1. Generate an API key: **Settings → API Keys → New Key**
+2. Add the Paca MCP server to your agent config (Claude Desktop example):
+
+```json
+{
+  "mcpServers": {
+    "paca": {
+      "command": "npx",
+      "args": ["-y", "@paca-ai/paca-mcp"],
+      "env": {
+        "PACA_API_KEY": "your-api-key-here",
+        "PACA_API_URL": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+See [mcp-server-setup.md](mcp-server-setup.md) for platform-specific instructions and advanced configuration.
+
+---
+
+## What to Read Next
+
+| Document | When to read it |
+|---|---|
+| [local-development.md](local-development.md) | Setting up a contributor environment |
+| [mcp-server-setup.md](mcp-server-setup.md) | Connecting AI agents via MCP |
+| [../architecture/overview.md](../architecture/overview.md) | Understanding the system architecture |
+| [../plugins/overview.md](../plugins/overview.md) | Writing or installing plugins |
+| [../../deploy/README.md](../../deploy/README.md) | Production deployment reference |
+| [../../CHANGELOG.md](../../CHANGELOG.md) | Release history |
diff --git a/docs/guides/local-development.md b/docs/guides/local-development.md
index c15cf4eb..0f3ada4f 100644
--- a/docs/guides/local-development.md
+++ b/docs/guides/local-development.md
@@ -1,40 +1,77 @@
 # Local Development
 
+## Quick Start
+
+One command starts the full stack with hot-reload from your local source files:
+
+```bash
+docker compose -f deploy/docker-compose.dev.yml up -d
+```
+
+Open `http://localhost`. All services watch the source tree and reload automatically — no manual rebuild needed.
+
+To stop:
+```bash
+docker compose -f deploy/docker-compose.dev.yml down
+```
+
+To also remove data volumes:
+```bash
+docker compose -f deploy/docker-compose.dev.yml down -v
+```
+
+---
+
 ## Runtime Stack
 
-| Service | Technology | Port |
-|---|---|---|
-| `apps/web` | React + Vite + shadcn/ui | 3000 |
-| `services/api` | Go + Gin | 8080 |
-| `services/realtime` | Node.js + Socket.IO | — (not scaffolded) |
-| `services/ai-agent` | FastAPI + LangGraph | — (not scaffolded) |
-| PostgreSQL | postgres:16-alpine | 5432 |
-| Valkey | valkey/valkey:8-alpine | 6379 |
+| Service | Technology | Port | Hot-reload |
+|---|---|---|---|
+| `apps/web` | React + TanStack Start + shadcn/ui | 3000 (via nginx on 80) | Vite HMR |
+| `services/api` | Go + Gin | 8080 (via nginx on 80) | [air](https://github.com/air-verse/air) |
+| `services/realtime` | Node.js + Socket.IO | 3001 (internal) | `bun --watch` |
+| `services/ai-agent` | Python + FastAPI + OpenHands SDK | 8082 (external) | source volume |
+| PostgreSQL | postgres:16-alpine | 5432 | — |
+| Valkey | valkey/valkey:8-alpine | 6379 | — |
+| MinIO S3 API | minio/minio | 9000 | — |
+| MinIO Console | minio/minio | 9001 | http://localhost:9001 (user: `minioadmin`, pass: `minioadmin`) |
+
+The nginx gateway (port 80) routes `/api/v1/…` to the API, socket traffic to realtime, and `/storage/…` to MinIO. `apps/web` is served at the root.
+
+---
 
 ## Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/) with the Compose plugin
-- Go 1.26+ (for `services/api`)
-- Node.js / Bun (for `apps/web`)
 
-## Start infrastructure
+That is the only hard requirement for the full containerized stack. The services build their own images from `Dockerfile.dev` in each service directory.
 
-All infra (PostgreSQL, Valkey) is defined in `deploy/docker-compose.dev.yml`. Run from the repository root:
+---
+
+## Infra Only
+
+If you only want PostgreSQL and Valkey (to run services on the host yourself):
 
 ```bash
 docker compose -f deploy/docker-compose.dev.yml up -d postgres valkey
 ```
 
-The Postgres schema is seeded automatically from `services/api/migrations/` on first start.
+---
+
+## Running Services on the Host
 
-## Start services
+For faster feedback loops or IDE-integrated debugging, you can run individual services directly on the host and point them at the containerized infra.
+
+**Prerequisites for host-side development:**
+- Go 1.23+ (for `services/api`)
+- Bun (for `apps/web` and `services/realtime`)
+- Python 3.12+ with [uv](https://docs.astral.sh/uv/) (for `services/ai-agent`)
 
 ### API (`services/api`)
 
 ```bash
 cd services/api
-cp .env.example .env   # first time only — credentials match docker-compose defaults
-make run
+cp .env.example .env   # first time — credentials match docker-compose defaults
+make run               # uses air for hot-reload
 ```
 
 ### Web (`apps/web`)
@@ -42,33 +79,56 @@ make run
 ```bash
 cd apps/web
 bun install            # first time only
-bun run dev            # http://localhost:3000
+bun run dev            # Vite dev server at http://localhost:3000
 ```
 
-Or run API + web in Docker alongside infra:
+### Realtime (`services/realtime`)
 
 ```bash
-docker compose -f deploy/docker-compose.dev.yml up -d
+cd services/realtime
+bun install            # first time only
+bun run dev
 ```
 
+### AI Agent (`services/ai-agent`)
+
+```bash
+cd services/ai-agent
+uv sync                # first time only
+uv run uvicorn src.main:app --reload --port 8000
+```
+
+---
+
 ## Migrations
 
-Migrations are plain SQL files under `services/api/migrations/` and run in lexicographic order. To apply them manually against a running Postgres instance:
+Migrations are plain SQL files under `services/api/migrations/` named in lexicographic order. They run automatically when the Postgres container first starts (mounted at `/docker-entrypoint-initdb.d`).
+
+To apply migrations manually against a running instance:
 
 ```bash
 cd services/api
-make migrate-up        # requires DATABASE_URL to be set
+make migrate-up   # requires DATABASE_URL to be set
 ```
 
-## Stop infra
+---
 
-```bash
-docker compose -f deploy/docker-compose.dev.yml down
-```
+## Default Dev Credentials
+
+| Resource | Value |
+|---|---|
+| App login | `admin` / `adminpassword` |
+| PostgreSQL | `paca:paca@localhost:5432/paca` |
+| MinIO console | `minioadmin` / `minioadmin` at http://localhost:9001 |
+| Agent API key | `dev-agent-api-key-change-in-production` |
+
+These are intentionally weak defaults — never use them in production.
 
-Use `down -v` to also remove the Postgres data volume.
+---
 
-## Architecture notes
+## Architecture Notes
 
-- `services/api` owns all persistent state changes and publishes domain events to a Valkey Stream.
-- `services/realtime` will consume those events and fan them out to Socket.IO clients.
\ No newline at end of file
+- `services/api` owns all persistent state changes and publishes domain events to Valkey Streams.
+- `services/realtime` consumes those events and fans them out to Socket.IO clients.
+- `services/ai-agent` reads agent trigger events from a separate Valkey Stream and manages Docker containers for OpenHands conversations.
+- `apps/mcp` is stateless; run it with `npx @paca-ai/paca-mcp` pointed at the running API.
diff --git a/docs/guides/mcp-server-setup.md b/docs/guides/mcp-server-setup.md
index 1980d656..9c1b2660 100644
--- a/docs/guides/mcp-server-setup.md
+++ b/docs/guides/mcp-server-setup.md
@@ -71,7 +71,7 @@ Claude Desktop provides the most seamless integration with the Paca MCP server.
 
 **Usage in Claude Desktop:**
 
-Once configured, Claude will automatically have access to all 86 Paca tools. You can ask Claude to:
+Once configured, Claude will automatically have access to all 81 Paca tools. You can ask Claude to:
 
 - "List all projects in my Paca workspace"
 - "Create a new task for user authentication"
diff --git a/services/README.md b/services/README.md
index 5e992098..52169141 100644
--- a/services/README.md
+++ b/services/README.md
@@ -2,10 +2,10 @@
 
 This directory contains backend runtime services.
 
-## Planned Services
+## Services
 
-- `api`: the Go + Gin application backend.
-- `realtime`: the Socket.IO real-time delivery service.
-- `ai-agent`: the FastAPI + LangGraph AI runtime.
+- `api` — Go + Gin application backend (business logic, REST API, WASM plugin runtime).
+- `realtime` — Node.js + Socket.IO real-time event fan-out.
+- `ai-agent` — Python + FastAPI + OpenHands SDK AI agent orchestration.
 
-Service boundaries are documented in [../docs/architecture/service-boundaries.md](../docs/architecture/service-boundaries.md).
\ No newline at end of file
+Service boundaries are documented in [../docs/architecture/service-boundaries.md](../docs/architecture/service-boundaries.md).
diff --git a/services/ai-agent/README.md b/services/ai-agent/README.md
index 6a0842b7..bca65136 100644
--- a/services/ai-agent/README.md
+++ b/services/ai-agent/README.md
@@ -1,12 +1,28 @@
 # AI Agent Service
 
-This directory is reserved for the FastAPI + LangGraph service.
+Python + FastAPI + OpenHands SDK service responsible for AI agent orchestration.
 
-## Planned Responsibilities
+## Overview
 
-- execute AI agent workflows;
-- expose AI-oriented service endpoints;
-- integrate with core backend workflows;
-- manage controlled runtime context for agents.
+This service:
 
-The expected Python layout should be documented when scaffolding begins.
\ No newline at end of file
+- Consumes agent trigger events from the `paca:agent:triggers` Valkey Stream.
+- Spawns isolated Docker containers via the OpenHands SDK (one per active conversation).
+- Runs OpenHands agent conversations with per-agent LLM, skills, MCP servers, and system prompt.
+- Publishes conversation events to the `paca:agent:events` Valkey Stream.
+- Exposes REST endpoints for pause, resume, stop, and conversation history.
+
+See [../../docs/ai-agent/ai-agent-service.md](../../docs/ai-agent/ai-agent-service.md) for full implementation details.
+
+## Run Locally
+
+```bash
+uv sync
+uv run uvicorn src.main:app --reload --port 8000
+```
+
+## Run Tests
+
+```bash
+uv run pytest
+```