paradoxbound · paradoxbound · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -28,41 +28,7 @@ npm start               # Run stdio server (node packages/stdio/dist/index.js)
 
 ## Architecture
 
-### Monorepo (v2.5.0)
-
-- **packages/core** (`@bookstack-mcp/core`) – Shared BookStack API client and types. Uses **native `fetch`** only (no axios). Entry: `packages/core/src/bookstack-client.ts` and `packages/core/src/types.ts`.
-- **packages/stdio** (`bookstack-mcp-stdio`) – MCP server with stdio transport. Imports `BookStackClient` and `BookStackConfig` from `@bookstack-mcp/core`. Entry: `packages/stdio/src/index.ts`.
-
-**Key Design Decisions:**
-- **Native fetch** – Core client uses only `fetch`; API errors set `error.status` and `error.response` for tool error handling.
-- **Stdio only** – Single transport for local, LibreChat, Claude Desktop.
-- **Workspaces** – Root `package.json` has `"workspaces": ["packages/core", "packages/stdio"]`; build/test at root run in workspaces.
-
-### Data Flow
-
-```
-MCP Client (LibreChat/Claude Desktop)
-  ↓
-Stdio Transport (packages/stdio)
-  ↓
-McpServer - ListTools/CallTool
-  ↓
-Tool handlers - call BookStackClient from @bookstack-mcp/core
-  ↓
-BookStackClient (native fetch) - API calls, response enhancement
-  ↓
-Enhanced JSON with URLs, previews, metadata
-```
-
-### Core Components
-
-**packages/core**
-- `src/bookstack-client.ts` – Fetch-based HTTP client, token auth, timeouts, `request()` / `requestForm()`; all entity methods; response enhancement (URLs, previews, dates).
-- `src/types.ts` – Shared types (BookStackConfig, Book, Page, Chapter, Shelf, etc.).
-- `tests/` – Functional tests (global-setup, read-tools, write-tools, write-gate); import `@bookstack-mcp/core`.
-
-**packages/stdio**
-- `src/index.ts` – Env validation, McpServer, tool registration (read + write when enabled), stdio transport. Error handling uses `error.status` / `error.response` (no axios).
+See [docs/architecture.md](docs/architecture.md) for the full architecture reference (monorepo structure, data flow, components, types, design decisions).
 
 ## Configuration
 
@@ -233,23 +199,6 @@ npm test   # runs packages/core tests
 - **packages/core** – No runtime deps; uses native `fetch`. Dev: typescript, vitest.
 - **packages/stdio** – `@bookstack-mcp/core`, `@modelcontextprotocol/sdk`, `zod`. Dev: typescript, tsx, @types/node.
 
-## Migration from v1.0
-
-### What Changed
-
-1. **Single entry point** - `src/index.ts` replaces multiple files
-2. **Modern API** - `McpServer` + `registerTool()` instead of manual handlers
-3. **Removed complexity** - No SSE, no supergateway, no separate transport layer
-4. **Stdio only** - Universal transport works everywhere
-5. **Zod schemas** - Type-safe input validation
-6. **Simpler deployment** - Just works with LibreChat and Claude Desktop
-
-### v2.5.0 Monorepo
-
-- **packages/core** – BookStack client + types; native `fetch` only (no axios).
-- **packages/stdio** – MCP server entry; depends on `@bookstack-mcp/core`.
-- Root `src/` removed; tests live in `packages/core/tests`. Docker and CI build from root; image runs `node packages/stdio/dist/index.js`.
-
 ## Debugging
 
 ### Check Server Output
@@ -280,72 +229,7 @@ curl -H "Authorization: Token $BOOKSTACK_TOKEN_ID:$BOOKSTACK_TOKEN_SECRET" \
 
 ## CI/CD Pipeline
 
-### Workflow Overview
-
-| Workflow | Trigger | Purpose |
-|---|---|---|
-| `functional-tests.yml` | PR + push to main | Build, type-check, run functional tests |
-| `docker-publish.yml` | PR + push to main | PR: Dockerfile validate + full CD pre-check. Post-merge: build, verify, merge manifest, tag, clean up |
-| `auto-tag.yml` | _(retired — no trigger)_ | Kept as documentation only; logic moved into docker-publish.yml |
-
-### PR Job Sequence (docker-publish.yml)
-
-```
-pull_request → main (same-repo only)
-  ↓
-build-and-push (matrix: amd64 + arm64)   fail-fast=true
-  │  build only — validates Dockerfile compiles cleanly (no push)
-  ↓ both must succeed
-pre-merge-cd-check
-  ├── build + push :pr-{n}-amd64 and :pr-{n}-arm64 to GHCR
-  ├── verify both PR arch images exist in registry
-  ├── create + verify test manifest :pr-{n}
-  ├── assert version not already tagged in registry
-  └── clean up all :pr-{n}-* images (always, even on failure)
-```
-
-### Post-merge Job Sequence (docker-publish.yml)
-
-```
-push to main
-  ↓
-build-and-push (matrix: amd64 + arm64)   fail-fast=true
-  ↓ both must succeed
-verify — inspect both digests in GHCR
-  ↓ either missing → cleanup job runs, workflow fails
-merge
-  ├── read version from packages/stdio/package.json
-  ├── assert version tag not already in registry
-  ├── create multi-arch manifest (:latest, :2.5.0, :2.5, :2)
-  ├── verify manifest is pullable
-  ├── create git tag (idempotent)
-  └── delete staging tags (:latest-amd64, :latest-arm64) via GHCR REST API
-  ↓ any step fails → cleanup job runs
-cleanup (runs on verify or merge failure)
-  └── delete :latest-amd64 and :latest-arm64 from GHCR via REST API
-```
-
-### Required GitHub Branch Protection Rules
-
-These settings **must** be configured in GitHub → Settings → Branches → main to enforce the PR gate. They cannot be set in workflow files.
-
-- **Require status checks to pass before merging**
-  - Required checks: `test` (functional-tests.yml), `build-and-push` (docker-publish.yml), and `pre-merge-cd-check` (docker-publish.yml)
-- **Require branches to be up to date before merging** — enabled
-- **Restrict who can push to matching branches** — block direct pushes to main
-- **Do not allow bypassing the above settings** — enabled
-
-Without these rules, GitHub will allow the merge button regardless of workflow results.
-
-> **Note:** `pre-merge-cd-check` only runs on same-repo PRs (not forks). Fork PRs cannot push to GHCR and will not have this check required.
-
-### Version Tagging Convention
-
-- Version is always read from `packages/stdio/package.json` (the published package).
-- The root `package.json` is `private: true` and is **not** the version source.
-- Bumping `packages/stdio/package.json` version and merging to main triggers a full release.
-- If the version tag already exists in GHCR, the pipeline fails early to prevent overwriting a released image.
-- Git tag (`vX.Y.Z`) is created **after** the registry manifest is verified — never before.
+See [docs/ci-cd.md](docs/ci-cd.md) for the full pipeline reference (workflow overview, job sequences, version tagging, branch protection rules).
 
 ## Future Plans
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -65,6 +65,17 @@ npm test
 
 Please do **not** open a public issue for security vulnerabilities. Use the process described in [SECURITY.md](SECURITY.md).
 
+## Requirements for acceptable contributions
+
+All pull requests must meet these requirements before they will be merged:
+
+1. **DCO sign-off** — every commit must have a `Signed-off-by` line (see above)
+2. **Type-check passes** — `npm run type-check` must succeed with no errors
+3. **Build passes** — `npm run build` must succeed
+4. **Tests pass** — `npm test` must pass (unit and fuzz tests run without credentials; functional tests require a live BookStack instance)
+5. **No new HIGH/CRITICAL vulnerabilities** — `npm audit --audit-level=high` must pass
+6. **Code style** — follow the conventions below
+
 ## Code style
 
 - TypeScript strict mode

diff --git a/README.md b/README.md
@@ -1,8 +1,22 @@
 # BookStack MCP Server
 
-[![OpenSSF Baseline](https://www.bestpractices.dev/projects/12116/baseline)](https://www.bestpractices.dev/projects/12116)
+[![OpenSSF Baseline](https://www.bestpractices.dev/projects/12116/baseline)](https://www.bestpractices.dev/projects/12116) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12116/badge)](https://www.bestpractices.dev/projects/12116)
 
-A modern Model Context Protocol (MCP) server for BookStack, providing AI assistants with full access to your BookStack documentation.
+BookStack stores your team's knowledge — but AI assistants can't access it without an integration. BookStack MCP Server bridges that gap, connecting AI assistants (Claude Desktop, LibreChat, and any MCP-compatible client) directly to your BookStack instance so they can search, read, and manage your documentation through natural language.
+
+## Obtaining the software
+
+- **Docker (recommended):** `docker pull ghcr.io/paradoxbound/bookstack-mcp:latest`
+- **npm:** `npx bookstack-mcp` (no installation required)
+- **Source:** Clone the repository and run `npm install && npm run build`
+
+Full setup instructions are in the [Quick Start](#quick-start) section below.
+
+## Feedback and contributing
+
+- **Bug reports and feature requests:** [Open an issue](https://github.com/paradoxbound/bookstack-mcp/issues)
+- **Security vulnerabilities:** Follow the process in [SECURITY.md](SECURITY.md) — do not open a public issue
+- **Contributing code or docs:** See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution process, DCO sign-off requirement, and code style requirements
 
 ## Features
 
@@ -97,19 +111,7 @@ mcpServers:
       # BOOKSTACK_ENABLE_WRITE: "false"  # Optional
 ```
 
-Or use local build:
-
-```yaml
-mcpServers:
-  bookstack:
-    command: node
-    args:
-      - /path/to/bookstack-mcp/packages/stdio/dist/index.js
-    env:
-      BOOKSTACK_BASE_URL: "https://your-bookstack.com"
-      BOOKSTACK_TOKEN_ID: "your-token-id"
-      BOOKSTACK_TOKEN_SECRET: "your-token-secret"
-```
+See [docs/librechat-integration.md](docs/librechat-integration.md) for advanced options, troubleshooting, and local build configuration.
 
 ### Docker
 
@@ -140,56 +142,15 @@ docker run --rm \
 
 ## Available Tools
 
+45 tools across two categories. See [docs/reference.md](docs/reference.md) for complete input/output documentation for every tool.
+
 ### Read Operations (Always Available)
 
-1. **get_capabilities** - Show current server capabilities
-2. **search_content** - Advanced search with filtering and pagination
-3. **search_pages** - Search specifically for pages with book filtering
-4. **get_books** - List books with advanced filtering and sorting
-5. **get_book** - Get detailed information about a specific book
-6. **get_pages** - List pages with previews and context
-7. **get_page** - Get full content of a specific page
-8. **get_chapters** - List chapters with filtering
-9. **get_chapter** - Get details of a specific chapter
-10. **get_shelves** - List book shelves (collections)
-11. **get_shelf** - Get shelf details with all books
-12. **get_attachments** - List attachments with filtering
-13. **get_attachment** - Get attachment details
-14. **export_page** - Export pages in various formats
-15. **export_book** - Export entire books
-16. **export_chapter** - Export chapters
-17. **get_recent_changes** - Get recently updated content
-18. **get_comments** - List comments with optional page filtering
-19. **get_comment** - Get comment details including replies
-20. **get_audit_log** - List audit log (system activity trail)
-21. **get_system_info** - BookStack version and instance info
-22. **get_users** - List users (read-only)
-23. **get_user** - Get user details (read-only)
-24. **get_recycle_bin** - List soft-deleted items
-25. **get_image_gallery** - List gallery images (read-only)
-26. **get_image** - Get gallery image details (read-only)
+`get_capabilities`, `search_content`, `search_pages`, `get_books`, `get_book`, `get_pages`, `get_page`, `get_chapters`, `get_chapter`, `get_shelves`, `get_shelf`, `get_attachments`, `get_attachment`, `export_page`, `export_book`, `export_chapter`, `get_recent_changes`, `get_comments`, `get_comment`, `get_audit_log`, `get_system_info`, `get_users`, `get_user`, `get_recycle_bin`, `get_image_gallery`, `get_image`
 
 ### Write Operations (Requires BOOKSTACK_ENABLE_WRITE=true)
 
-27. **create_book** - Create new books
-28. **update_book** - Update existing books
-29. **delete_book** - Delete books
-30. **create_chapter** - Create new chapters
-31. **update_chapter** - Update existing chapters
-32. **delete_chapter** - Delete chapters
-33. **create_page** - Create new pages
-34. **update_page** - Update existing pages
-35. **delete_page** - Delete pages
-36. **create_shelf** - Create new shelves
-37. **update_shelf** - Update existing shelves
-38. **delete_shelf** - Delete shelves
-39. **create_attachment** - Create link attachments
-40. **upload_attachment** - Upload file attachments from local filesystem
-41. **update_attachment** - Update attachments
-42. **delete_attachment** - Delete attachments
-43. **create_comment** - Create comments on pages (with reply support)
-44. **update_comment** - Update comment content or archive status
-45. **delete_comment** - Delete comments
+`create_book`, `update_book`, `delete_book`, `create_chapter`, `update_chapter`, `delete_chapter`, `create_page`, `update_page`, `delete_page`, `create_shelf`, `update_shelf`, `delete_shelf`, `create_attachment`, `upload_attachment`, `update_attachment`, `delete_attachment`, `create_comment`, `update_comment`, `delete_comment`
 
 ## BookStack API Setup
 
@@ -242,18 +203,22 @@ Tests are self-seeding: they create all required data on the instance and clean
 ## Project Structure
 
 ```
-packages/
-├── core/                 # @bookstack-mcp/core – shared client & types
-│   ├── src/
-│   │   ├── bookstack-client.ts   # BookStack API (native fetch)
-│   │   └── types.ts             # Shared types
-│   ├── tests/                  # Functional tests
-│   └── dist/
-└── stdio/                # bookstack-mcp-stdio – MCP server
-    ├── src/
-    │   └── index.ts            # MCP tools + stdio transport
-    └── dist/
-        └── index.js            # Entry point (npm start / Docker)
+bookstack-mcp/
+├── docs/                 # Project documentation
+│   ├── reference.md      # Tool reference (all 45 tools, input/output)
+│   ├── architecture.md   # Architecture and data flow
+│   ├── ci-cd.md          # CI/CD pipeline reference
+│   └── librechat-integration.md
+├── packages/
+│   ├── core/             # @bookstack-mcp/core – shared client & types
+│   │   ├── src/
+│   │   │   ├── bookstack-client.ts   # BookStack API (native fetch)
+│   │   │   └── types.ts             # Shared types
+│   │   └── tests/                   # Unit, fuzz, and functional tests
+│   └── stdio/            # bookstack-mcp-stdio – MCP server
+│       └── src/
+│           └── index.ts             # MCP tools + stdio transport
+└── package.json          # Root workspace (private: true)
 ```
 
 ## Response Enhancements
@@ -387,7 +352,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on making changes, running
 
 ## License
 
-MIT License - see LICENSE file for details
+This project is released under the [MIT License](LICENSE) (SPDX: `MIT`), an [OSI-approved](https://opensource.org/license/mit) permissive free and open-source software license.
 
 ## Links