docs: bring the documentation up to the 5.4 alphas

[pjdoland]

Summary

The changelog stopped at 5.1.0, with everything since sitting in a single [Unreleased] block, even though 5.2.0, 5.2.1, 5.3.0, and 5.3.1 have all shipped to PyPI and 5.4.0 has two alphas out. Along the way I checked the rest of the documentation against the code, and several documented behaviors had drifted far enough to be actively wrong. This brings everything current through 5.4.0a2, on the assumption the alpha work lands as 5.4.0.

Docs only. No code changes.

Changelog

The existing [Unreleased] block turned out to be exactly 5.2.0's content, so it is retitled and dated rather than rewritten. Adds the four missing sections plus a 5.4.0 section for the alphas:

Section	Covers
[5.4.0] - unreleased	ACP agent mode (#378), proxied Jupyter UI tools MCP server (#398), dependency floor raise (#399), and the hard-break (#384), inline-code (#401), and IME (#400) fixes
[5.3.1] - 2026-07-29	Skills import size cap scoping (#394)
[5.3.0] - 2026-07-22	Multi-language and kernel-aware notebooks (#379), usage footer (#391), telemetry split (#383), Claude model defaults (#389), context budget (#390), and three containment and context fixes
[5.2.1] - 2026-06-26	Tool-approval timeout (#381)
[5.2.0] - 2026-06-18	The former [Unreleased] content

Dates come from the PyPI upload records and the GitHub releases, not from commit dates. 5.3.0 gets a migration note for the ruleset frontmatter key it removed.

Corrections, not just additions

The audit turned up documentation that would mislead someone following it:

• docs/rulesets.md documented frontmatter that raises. Both examples in the file used scope.kernels, which 5.3.0 turned into a hard ValueError. Copying either one out of the docs produced a rule that failed to load.
• directories: has never been a real key. The frontmatter reference listed it; the code reads directory_patterns. A rule scoped with directories parses fine and silently applies everywhere, which is worse than an error. The reference now also covers languages, kernel_names, and cell_types, none of which were documented, and corrects the stated default priority from 100 to 0.
• The Rules tab does not exist. The management section told users to toggle rules in a Settings tab. There is no such tab; the frontend has no rules UI at all. Replaced with what actually works: active: false in the file, and the three REST routes the server does expose. I also noted that apply is parsed, validated, and reported by the rules API but never consulted when selecting rules, since documenting it as a control would be misleading.
• The admin guide said NBI has no Python test suite ("currently TypeScript-only; end-to-end Python testing is a future work item"), as did CONTRIBUTING. There are around 1,400 tests and CI has been running them. Both corrected, with the invocation.
• The version matrix stopped at 5.1.x, and the pin example recommended mcp==1.27.*, which no longer satisfies the floor. The surrounding text also said mcp carries no upper bound; it is capped below 2.0, because 2.x moved the FastMCP server out of the SDK and the extension fails to load against it.
• The README said MCP prompts are not supported. They are, and have been since before 5.1.0.

Additions

• Admin guide: a section for the proxied Jupyter UI tools MCP server, its five NBI_UI_TOOLS_* environment variables, and the /notebook-intelligence/ui-tools route (missing from the route table). Plus NBI_CLAUDE_INLINE_COMPLETION_MAX_TOKENS and NBI_ACP_AGENT_COMMAND, which were the only two environment variables added since 5.1.0 that nothing documented.
• README: the opt-in per-turn usage footer and why the cost figure is withheld off a first-party endpoint, the current Claude model defaults and the auto-complete output cap, and a section on multi-language and kernel-aware notebooks.

Fact-checking

Every code-level claim in the new text was checked against the source rather than against commit subjects or PR titles. That changed the outcome twice:

• The fix(built-in-tools): confine search_files glob matches to workspace #386 entry originally described a glob enumeration problem. It is a confidentiality issue: search_files sandboxed only the search root and then opened each hit directly, so a workspace symlink pointing outside it let an agent read arbitrary host files through content_pattern matches.
• The fix(built-in-tools): resolve symlink dir containment before probing it #387 entry originally said an outbound symlink "passed the check". It did not; the containment check still rejected it. The defect was that is_dir(follow_symlinks=True) ran on the target before the check, so the probe itself reached past the boundary.

Also verified by execution rather than reading: every frontmatter block now in docs/rulesets.md parses, and the two claims added about directory_patterns (fnmatch semantics, and that a bare path does not match its own children) were run through the matcher. All 16 issue and PR numbers cited resolve. All internal links and anchors across the doc set resolve.

Checks: pytest tests/ 1437 passed, jlpm test 381 passed, prettier --check clean on every markdown file.

One thing I did not change

While verifying the MCP prompt syntax I was about to document, parse_prompt in ai_service_manager.py turned out to require a third colon (/mcp:server:prompt:input) before it recognizes an MCP prompt at all, while the chat input's autocomplete offers /mcp:server:prompt and the function's own comment documents /mcp:server_name:prompt_name input. Typing input after the autocompleted form leaves command empty and the whole string falls through as plain input. I left the code alone and kept the README to what I could verify (that prompts are supported and appear in the slash-command autocomplete), rather than documenting either form as working. Worth a look separately.