# Agent Instructions

## Documentation consistency (hard rule)

Documentation must never contradict the code:

- **Check before you write.** Before changing or adding any doc, verify every claim
  (commands, binaries, tool names, env vars, parameters, tool counts) against the
  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`, `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).