refactor: update documentation

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.
+For security vulnerabilities, see [SECURITY.md](SECURITY.md).

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.
+- 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.

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 |
 

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.
+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.

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.
+The app layer stays focused on user experience, presentation concerns, and tooling that directly exercises the product surface.

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.

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...",

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]

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.