docs: docs-consistency check per new AGENTS.md rule

- AGENTS.md now carries all agent guidance (architecture, commands,
  env vars, tool pattern, type safety); CLAUDE.md is a thin pointer
  importing it via @AGENTS.md
- fixed stale claims: removed chmod-from-build note, dropped fragile
  line-number reference (src/mcp/index.ts:27-54), generated types
  now documented as schema-types.ts + graphql.ts (codegen 7 layout)
- README: binary-name accurate npx commands (-- npx -p ...
  wikijs-mcp-edit — the documented 'npx @cahaseler/wikijs-mcp' was
  the exact wikijs-mcp-edit:not-found trap), 16-tool list matches
  src/mcp/index.ts registration incl. write-gate, testing section
  documents stdio behavior + --version + inspector + env failure mode,
  WIKIJS_DEFAULT_LOCALE documented, prerequisites match eslint-10
  tooling floor, troubleshooting gains the not-found gotcha
- verified empirically: --version output, missing-env abort message,
  make build, lint (flat config live), jest 2/2
- known asymmetry documented (not hidden): create_page zod locale
  default is hardcoded 'en', WIKIJS_DEFAULT_LOCALE only affects
  URL building

AGENTS.md

@@ -9,10 +9,66 @@ Documentation must never contradict the code:
   actual state of `package.json`, `src/` and the build output. No stale instructions.
 - **Code and docs change in the same commit.** Every change that alters the public
   surface — tools added/removed, env vars, CLI flags, binary names, npm scripts,
-  dependency majors — must update `README.md`, `CLAUDE.md` (tool list) and
+  dependency majors — must update `README.md`, `AGENTS.md` (tool list) and
   `env.example` in the same change.
+- **No fragile line-number references.** Cite files and symbols, not line ranges
+  (they go stale with every edit).
 - **Commands must be copy-paste runnable.** Example commands in docs must work as
   written (correct binary names, required env vars shown). Prefer documenting the
   happy path plus the exact failure mode when a missing env var is required.
 - **When in doubt, verify empirically.** Run the command in the docs before
   committing it (`--version` smoke, or a dry call), the same way code is verified.
+
+## Project overview
+
+Model Context Protocol (MCP) server bridging AI assistants with WikiJS v2.5
+instances (GraphQL API). Three-layer architecture:
+
+1. **MCP layer** (`src/mcp/`) — `WikiJSMcpServer` manages lifecycle and tool
+   registration in `src/mcp/index.ts`; each tool is a module in `src/mcp/tools/`.
+2. **WikiJS client layer** (`src/wikijs/`) — `WikiJSClient` wraps GraphQL
+   operations via the codegen SDK; queries in `src/wikijs/queries/pages.graphql`;
+   generated types in `src/wikijs/generated/` (`schema-types.ts` + `graphql.ts`).
+3. **Entry point** (`src/index.ts`) — config from environment, stdio transport,
+   `--version` flag for smoke tests.
+
+### Tool pattern
+
+Every tool in `src/mcp/tools/` exports:
+- `PARAMETERS` — Zod schema for runtime validation
+- `createTool(wikiClient)` — returns the `ToolCallback` handler
+
+Registration order and the `WIKIJS_ENABLE_EDIT` write-gate live in
+`src/mcp/index.ts`. Write tools (`create_page`, `edit_page`, `move_page`,
+`delete_page`, `restore_page_version`, `convert_page_editor`) are only
+registered when edits are enabled.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `npm run build` | tsc compile to `build/` |
+| `npm run lint` / `npm run lint:fix` | eslint (flat config, `eslint.config.js`) |
+| `npm test` | jest with `ts-jest` ESM preset (needs `NODE_OPTIONS='--experimental-vm-modules'`, set by the script) |
+| `npm run codegen` | regenerate GraphQL types; introspects `${WIKIJS_URL}/graphql` (needs `WIKIJS_URL` reachable, runs via dotenv) |
+| `make build` / `make clean` | build / remove `build/` |
+| `docker-compose up -d` | local WikiJS + PostgreSQL on `http://localhost:3000` |
+
+## Environment variables
+
+- `WIKIJS_URL` — Wiki.js base URL without `/graphql` (required)
+- `WIKIJS_API_KEY` — Bearer token from Admin → API Access (required)
+- `WIKIJS_ENABLE_EDIT` — `true` enables the write tools (default off)
+- `WIKIJS_DEFAULT_LOCALE` — only used for URL building; the `create_page`
+  zod default for `locale` is hardcoded `'en'` (known asymmetry, see
+  `src/mcp/tools/createPage.ts`)
+
+`.env` is loaded via dotenv; copy `env.example` as template.
+
+## Type safety
+
+- TypeScript strict, `NodeNext` module resolution — relative imports need
+  `.js` extensions in source files.
+- Generated types are committed; do not hand-edit `src/wikijs/generated/`
+  (eslint ignores it).
+- Zod schemas validate tool parameters at runtime (zod v4).

CLAUDE.md

@@ -1,83 +1,7 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code (claude.ai/code) working in this repository.
 
-## Commands
+Project instructions live in AGENTS.md — this file imports it:
 
-### Build Commands
-- `npm run build` - Compiles TypeScript to JavaScript and sets executable permissions
-- `make build` - Alternative build command using Makefile
-- `npm run codegen` - Generates TypeScript types from WikiJS GraphQL schema (requires WIKIJS_URL in .env)
-
-### Development Commands
-- `make run` - Builds and runs the MCP server
-- `make clean` - Removes build artifacts
-- `docker-compose up -d` - Starts a local WikiJS instance for testing
-- `docker-compose down` - Stops the local WikiJS instance
-
-## Architecture
-
-This is a Model Context Protocol (MCP) server that bridges AI assistants with WikiJS instances. The architecture follows a three-layer pattern:
-
-### Core Components
-
-1. **MCP Layer** (`src/mcp/`)
-   - `WikiJSMcpServer` class manages the MCP server lifecycle and tool registration
-   - Tools are registered in `src/mcp/index.ts:27-54` with specific parameter schemas
-   - Each tool is a separate module in `src/mcp/tools/`
-
-2. **WikiJS Client Layer** (`src/wikijs/`)
-   - `WikiJSClient` class wraps GraphQL operations
-   - Uses generated GraphQL types from `src/wikijs/generated/graphql.ts`
-   - GraphQL queries are defined in `src/wikijs/queries/pages.graphql`
-
-3. **Entry Point** (`src/index.ts`)
-   - Initializes WikiJS client with URL and API key from environment
-   - Creates MCP server instance and connects via stdio transport
-   - Handles fatal errors and process exit
-
-### Tool Architecture
-
-Each MCP tool follows a consistent pattern:
-- Exports a `createTool` function that returns a handler
-- Exports a `PARAMETERS` schema for validation
-- Uses Zod for runtime parameter validation
-- Returns structured responses with content arrays
-
-### GraphQL Integration
-
-The project uses GraphQL Code Generator to create typed SDK from WikiJS API:
-- Schema is fetched from `${WIKIJS_URL}/graphql`
-- Queries in `.graphql` files generate TypeScript types
-- SDK provides type-safe methods for WikiJS operations
-
-## Environment Configuration
-
-Required environment variables (set in `.env`):
-- `WIKIJS_URL` - Base URL of WikiJS instance (without /graphql)
-- `WIKIJS_API_KEY` - Bearer token for WikiJS API authentication
-
-## Type Safety
-
-The project uses TypeScript with strict typing:
-- Generated GraphQL types ensure API contract compliance
-- Zod schemas validate MCP tool parameters at runtime
-- All async operations are properly typed
-
-## MCP Tools Available
-
-Read (always available):
-- `search_pages` - Full-text search across WikiJS pages
-- `get_page_by_id` - Retrieve specific page by numeric ID
-- `get_page_by_path` - Retrieve page by path and locale
-- `get_all_pages` - List pages with optional filters (limit/locale/tags)
-- `get_page_history` - Revision history of a page
-- `get_page_version` - A specific version of a page
-- `get_page_tree` - Page tree of a site
-- `list_tags` / `search_tags` - Tags
-- `get_page_links` - Page link graph for a locale
-
-Write (only available when WIKIJS_ENABLE_EDIT=true):
-- `create_page` - Create a new WikiJS page
-- `edit_page` - Edit a WikiJS page by ID (full-document replace; metadata preserved when omitted)
-- `move_page`, `delete_page`, `restore_page_version`, `convert_page_editor`
+@AGENTS.md

README.md

@@ -13,12 +13,12 @@ This MCP server enables AI assistants to interact with WikiJS instances by provi
 
 ## Installation
 
-### Using npx (recommended)
+### Using npx (published package)
 ```bash
-npx @cahaseler/wikijs-mcp
+# NOTE: the binary is named wikijs-mcp-edit, not after the package name:
+npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit
 ```
-
-The binary will be available as `wikijs-mcp-edit` to avoid conflicts with the original package.
+This always runs the *latest published* version from npm. For the current feature branch (see git remote), build from source instead.
 
 ### From source
 ```bash
@@ -38,14 +38,21 @@ npm run build
 claude mcp add wikijs \
   -e WIKIJS_URL=https://your-wiki.example.com \
   -e WIKIJS_API_KEY=your-api-key \
-  -- npx @cahaseler/wikijs-mcp
+  -- npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit
+
+# Or, when running from a local clone (uses your build instead of the
+# published package):
+claude mcp add wikijs \
+  -e WIKIJS_URL=https://your-wiki.example.com \
+  -e WIKIJS_API_KEY=your-api-key \
+  -- node /absolute/path/to/wikijs-mcp/build/index.js
 
 # Or with edit functionality enabled
 claude mcp add wikijs \
   -e WIKIJS_URL=https://your-wiki.example.com \
   -e WIKIJS_API_KEY=your-api-key \
   -e WIKIJS_ENABLE_EDIT=true \
-  -- npx @cahaseler/wikijs-mcp
+  -- npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit
 ```
 
 #### Method 2: Project-scoped configuration
@@ -55,7 +62,7 @@ Create a `.mcp.json` file in your project root:
   "mcpServers": {
     "wikijs": {
       "command": "npx",
-      "args": ["@cahaseler/wikijs-mcp"],
+      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
       "env": {
         "WIKIJS_URL": "https://your-wiki.example.com",
         "WIKIJS_API_KEY": "your-api-key",
@@ -73,7 +80,7 @@ Add to your Cursor settings (`.cursor/settings.json`):
   "mcpServers": {
     "wikijs-mcp": {
       "command": "npx",
-      "args": ["@cahaseler/wikijs-mcp"],
+      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
       "env": {
         "WIKIJS_URL": "https://your-wiki.example.com",
         "WIKIJS_API_KEY": "your-api-key",
@@ -95,7 +102,7 @@ Add to your Claude Desktop configuration:
   "mcpServers": {
     "wikijs-mcp": {
       "command": "npx",
-      "args": ["@cahaseler/wikijs-mcp"],
+      "args": ["-p", "@cahaseler/wikijs-mcp", "wikijs-mcp-edit"],
       "env": {
         "WIKIJS_URL": "https://your-wiki.example.com",
         "WIKIJS_API_KEY": "your-api-key",
@@ -121,38 +128,57 @@ Add to your Claude Desktop configuration:
 
 | Variable | Description | Required | Default |
 |----------|-------------|----------|---------|
-| `WIKIJS_URL` | URL of your WikiJS instance | Yes | - |
+| `WIKIJS_URL` | URL of your WikiJS instance (without `/graphql`) | Yes | - |
 | `WIKIJS_API_KEY` | WikiJS API key | Yes | - |
 | `WIKIJS_ENABLE_EDIT` | Enable page editing functionality | No | false |
+| `WIKIJS_DEFAULT_LOCALE` | Locale used when building page URLs | No | en |
 
 ## Available Tools
 
-Once configured, the following tools will be available:
+Once configured, the following tools will be available (10 read / 6 write):
 
+**Read (always available):**
 - **search_pages** - Search for pages by query string
   - Parameters: `query` (required), `path` (optional), `locale` (optional)
-  
-- **get_page_by_id** - Retrieve a specific page by its ID
+- **get_page_by_id** - Retrieve a specific page by its ID (full page incl. rendered content)
   - Parameters: `id` (required)
-  
 - **get_page_by_path** - Retrieve a page by its path and locale
   - Parameters: `path` (required), `locale` (required)
-  
-- **get_all_pages** - List all pages with optional filters
-  - Parameters: `limit` (optional), `locale` (optional), `tags` (optional)
-  
-- **create_page** - Create a new WikiJS page (only when `WIKIJS_ENABLE_EDIT=true`)
-  - Parameters: `title` (required), `content` (required), `description` (required), `path` (required), `editor` (optional), `isPublished` (optional), `isPrivate` (optional), `locale` (optional), `tags` (optional)
-  
-- **edit_page** - Edit a WikiJS page (only when `WIKIJS_ENABLE_EDIT=true`)
-  - Parameters: `id` (required), `title`, `content`, `description`, `editor`, `isPublished`, `isPrivate`, `locale`, `tags`, `path`
+- **get_all_pages** - List pages with optional filters
+  - Parameters: `limit` (optional, max 500), `locale` (optional), `tags` (optional)
+- **get_page_history** - Revision history of a page
+  - Parameters: `id` (required), `offsetPage` (optional), `offsetSize` (optional, max 200)
+- **get_page_version** - A specific revision of a page
+  - Parameters: `pageId` (required), `versionId` (required)
+- **get_page_tree** - Page tree of the site
+  - Parameters: `locale` (required), `mode` (optional, `FOLDERS`/`PAGES`/`ALL`, default `PAGES`), `path` (optional), `parent` (optional), `includeAncestors` (optional)
+- **list_tags** - List all tags
+- **search_tags** - Search tags
+  - Parameters: `query` (required)
+- **get_page_links** - Link graph of all pages for a locale
+  - Parameters: `locale` (required)
+
+**Write (only available when `WIKIJS_ENABLE_EDIT=true`):**
+- **create_page** - Create a new WikiJS page
+  - Parameters: `title`, `content`, `description`, `path` (required); `editor` (default `markdown`), `isPublished` (default `true`), `isPrivate` (default `false`), `locale` (optional, default `en`), `tags` (optional)
+- **edit_page** - Edit a WikiJS page by its ID. **Full-document replace for `content`**; all other fields are optional — omitted fields keep their existing values (metadata is never wiped by omission)
+  - Parameters: `id`, `content` (required); `title`, `description`, `path`, `editor`, `isPublished`, `isPrivate`, `locale`, `tags` (optional)
+- **move_page** - Move a page to a new path/locale
+  - Parameters: `id`, `destinationPath`, `destinationLocale` (required)
+- **delete_page** - Delete a page
+  - Parameters: `id` (required)
+- **restore_page_version** - Restore a previous version
+  - Parameters: `pageId`, `versionId` (required)
+- **convert_page_editor** - Convert a page to another editor type
+  - Parameters: `id`, `editor` (required e.g. `markdown`, `visual`)
 
 ## Development
 
 ### Prerequisites
-- Node.js 18+
+- Node.js 18+ at runtime for the built server (`engines` in package.json)
+- Node.js 20.19+ for development tooling (eslint 10 requires `^20.19 || ^22.13 || >=24`)
+- npm or pnpm
 - Docker (for local WikiJS testing)
-- npm or yarn
 
 ### Setup
 
@@ -198,14 +224,22 @@ make build
 
 ### Testing the MCP Server
 
+The server is a stdio MCP server — it is started *by* an MCP client, not manually as a daemon.
+
 ```bash
-# Run the built server
-node build/index.js
+# Quick smoke without a wiki connection: expect output = version from package.json
+node build/index.js --version
+
+# Run it manually (it then waits, silently, for MCP protocol frames on stdio):
+WIKIJS_URL=http://localhost:3000 WIKIJS_API_KEY=your-key node build/index.js
 
-# Or use the make command
-make run
+# Interactive verify the tools without a full client setup (browser UI, default http://localhost:6274):
+npx @modelcontextprotocol/inspector node build/index.js
 ```
 
+Missing env vars abort the server immediately with
+`WIKIJS_URL and WIKIJS_API_KEY must be set` on stderr.
+
 ## Security Considerations
 
 - **API Key Storage**: Never commit your API key to version control
@@ -220,8 +254,14 @@ Ensure your environment variables are properly configured. Check your `.env` fil
 ### "Failed to update page: Unauthorized"
 Your API key may be expired or lack the necessary permissions. Create a new API key with appropriate permissions.
 
+### `sh: wikijs-mcp-edit: not found` when running `npx @cahaseler/wikijs-mcp`
+npx fetched the package but looked for a binary named after the package. The binary is called `wikijs-mcp-edit`:
+```bash
+npx -p @cahaseler/wikijs-mcp wikijs-mcp-edit
+```
+
 ### GraphQL errors during development
-If you modify the GraphQL queries, regenerate the types:
+If you modify the GraphQL queries, regenerate the types (requires `WIKIJS_URL` reachable — it introspects your Wiki.js instance):
 ```bash
 npm run codegen
 ```