Skip to content

docs: cover post-4.8.0 changes across README, admin guide, skills, CHANGELOG#287

Merged
mbektas merged 2 commits into
plmbr:mainfrom
pjdoland:docs/post-4.8.0
May 17, 2026
Merged

docs: cover post-4.8.0 changes across README, admin guide, skills, CHANGELOG#287
mbektas merged 2 commits into
plmbr:mainfrom
pjdoland:docs/post-4.8.0

Conversation

@pjdoland
Copy link
Copy Markdown
Collaborator

Summary

The docs were getting behind: v4.8.0 was tagged but never got a CHANGELOG entry, and the three big Settings tabs (Skills as a top-level tab, Claude MCP, Claude Plugins) plus the new launcher tiles, Copilot model discovery, terminal drag-drop, and assorted admin-policy knobs that have merged since were under-documented across README, the admin guide, and `docs/skills.md`. This PR is a catch-up pass, not a comprehensive refresh.

I think we should do another doc update before 5.0 to revisit voice, deduplication between README and the admin guide, and the Failure-modes / Version-matrix tables more holistically. But I didn't want things to get too far behind in the meantime, so this PR ships the load-bearing corrections now and flags the rest as follow-up.

What this PR does

CHANGELOG.md

  • Backfills the missing `[4.8.0]` entry from the `v4.7.0..v4.8.0` merge range.
  • Adds an `[Unreleased]` section covering the post-4.8.0 work: three new Settings tabs and their management policies, four new launcher tiles, dynamic GitHub Copilot model discovery, terminal drag-drop with its upload-staging tunables, real progress feedback for long Claude tasks, and the fix-only entries from the same window.

README.md

  • New `Claude MCP Servers` and `Claude Plugins` sections.
  • Glossary entries for `Skill` and `Claude plugin` so the new sections read cold.
  • Expanded launcher-tile subsection covering opencode, Pi, GitHub Copilot CLI, and Codex.
  • Skills section reworded so it's clear the tab is now visible in any mode and that the manifest is admin-only.

docs/admin-guide.md

  • Env-var table rows for the four new CLI path overrides, the upload tunables, and the skill archive cap.
  • HTTP API table rows for `/claude-mcp/` and `/plugins/`, with the gates named correctly.
  • New `Disabling terminal drag-drop file attach` section under "Restricting features" with the trust-model note (this is the most security-relevant addition in the release and previously had no dedicated section).
  • Four new Failure-modes rows: plugin install failure, marketplace fetch from GHE, Copilot model-list failure, upload 413.
  • Version matrix extended through 4.8.x.
  • Security-model bullet (3) refreshed to cite `allow_github_skill_import` / `allow_github_plugin_import` instead of saying "network-layer only."

docs/skills.md

  • First paragraph updated to reflect the top-level tab.
  • Stale "no flag exists" paragraph replaced with the real `allow_github_skill_import` / `NBI_ALLOW_GITHUB_SKILL_IMPORT` flag plus a pointer to `skills_management_policy` for stricter posture.

Review process

Four persona agents (technical writing, accuracy / code-truth, end-user, operator) reviewed the changes before commit. Fix-before-merge findings applied:

  • `claude_plugins_management_policy` corrected throughout (I'd written `plugins_management_policy` in a couple of places).
  • `/plugins//` is POST and DELETE, not GET/DELETE+PATCH (enable/disable goes through POST with an `action` body).
  • Codex tile attribution split out: PR feat(launcher): add tiles for opencode, Pi, and GitHub Copilot CLI #268 covers opencode, Pi, and GitHub Copilot CLI; Codex was a separate commit.
  • Glossary entries for Skill and Claude plugin added so a first-time reader can parse the new sections.

Risks / follow-ups

No code changes; doc-only. Cross-checked against `extension.py`, `util.py`, and `skill_github_import.py` for the env vars, traitlets, HTTP routes, and defaults.

What I'd still revisit before 5.0:

  • The env-var table in the admin guide claims to be "the full surface" but several pre-4.8.0 Claude-agent timeout env vars (`NBI_CLAUDE_AGENT_*`) and the MCP timeout aren't listed. Out of scope for this PR but worth a dedicated pass.
  • README and admin guide duplicate the upload-tunables description; one of them should become the source of truth and the other should link.
  • A few CHANGELOG bullets are short and could grow more detail with help from the original authors.

Testing

Doc-only. Verified:

  • `pytest tests/` and `jlpm tsc` still pass with no code touched.
  • All cross-doc anchors (`#disabling-the-skills-tab`, `#disabling-the-plugins-tab`, `#disabling-user-initiated-github-imports`, `#github-auth-for-marketplace-add`) resolve to real headings.
  • No em dashes in the added prose.

…ANGELOG

Backfills the missing v4.8.0 entry and adds an Unreleased section to
CHANGELOG.md covering the work that has merged since the v4.8.0 tag:
the three new Settings tabs (Skills as top-level, Claude MCP Servers,
Claude Plugins) and their management policies, the new launcher tiles
for opencode, Pi, GitHub Copilot CLI, and Codex, dynamic GitHub Copilot
model discovery, terminal drag-drop file attach and its upload-staging
tunables, real progress feedback for long Claude tasks, and the rest of
the bug fixes that landed in the same window.

README gains short sections for Claude MCP Servers and Claude Plugins,
a glossary entry for Skill and Claude plugin, an expanded launcher-tile
subsection covering the four new CLIs, and clarifying language so a
first-time reader can tell which MCP tab they are looking at. The
admin guide gains rows in the env-var table for the new CLI path
overrides, the upload tunables, and the skill archive cap, plus rows in
the HTTP API table for the claude-mcp and plugins routes, a Terminal
drag-drop section under "Restricting features" with a trust-model note,
and Failure-modes coverage for plugin install, marketplace fetch,
Copilot model discovery, and 413s on the upload endpoint. docs/skills.md
loses the "no flag exists" paragraph that referenced a now-shipped flag.

Reviewed by four persona agents (technical writing, accuracy, end user,
operator). Findings applied include: correct claude_plugins_management_policy
name throughout, fix the /plugins/<scope>/<name> HTTP verbs (POST and
DELETE, not GET+DELETE+PATCH), refresh the Security model bullet, and
move the launcher-tile prose so it does not contradict its parent
section. Out-of-scope finding skipped: documenting pre-4.8.0 env vars
that were never in the table to begin with.
@pjdoland pjdoland added the documentation Improvements or additions to documentation label May 17, 2026
@mbektas mbektas merged commit 2fb44cf into plmbr:main May 17, 2026
4 checks passed
pjdoland added a commit to pjdoland/notebook-intelligence that referenced this pull request May 22, 2026
Promotes the [Unreleased] CHANGELOG snapshot to [5.0.0] - 2026-05-22
and expands it to cover everything merged into upstream/main after
PR plmbr#287's docs refresh. Bumps package.json to 5.0.0.

CHANGELOG additions cover the post-plmbr#287 surface:

- Settings tabs: plugin marketplace picker (plmbr#284), plugin marketplace
  details + Update button (plmbr#303), per-workspace MCP disable (plmbr#286),
  JSON-paste path in Add MCP server (plmbr#285).
- Launchers: hide-with-policy (plmbr#288), brand icons for Codex / opencode
  (plmbr#325, plmbr#333), per-launch directory picker (plmbr#332).
- Chat sidebar and agentic UX: workspace @-mention in Claude mode
  (plmbr#327), reload-open-files-on-disk (plmbr#330), steered system prompt
  away from over-eager notebook creation (plmbr#336).
- Skills: multi-manifest support (plmbr#321), tracks-upstream for user-
  imported skills (plmbr#322), HTTP kill switch for the reconciler (plmbr#291).
- Accessibility: full sub-section covering plmbr#305-plmbr#320.
- Security: shell-tool sandbox (plmbr#290), Claude UI-bridge sandbox (plmbr#323),
  0o600 on encrypted token (plmbr#293), env-secret scrubbing (plmbr#295), MCP
  config shape validation (plmbr#299), XSS allowlist (plmbr#296), Copilot WS
  auth + origin (plmbr#301), GHE host detection (plmbr#292), fastmcp -> mcp SDK
  swap (plmbr#324).
- Fixed: session listing unification (plmbr#310), session preview unwrap
  (plmbr#331), down-area runtime throw (plmbr#330 follow-up), WS message-handler
  leak (plmbr#294).
- Removed: fastmcp dependency, history.jsonl session gate.

Adds a Migration note covering the five behavior changes operators
should review before upgrading from 4.x: fastmcp swap, path
sandboxes, history.jsonl gate removal, workspace @-mention pointer
shape, and the Copilot WebSocket auth/origin tightening.

Two reviewer rounds (six personas each) applied:
- Round 1 caught security overclaims (plmbr#293, plmbr#299, plmbr#323), the
  plmbr#284/plmbr#303 mis-attribution, missing migration note, 3 em dashes,
  and the stale `fastmcp==2.x.*` recommendation in the admin guide.
- Round 2 caught the missing plmbr#301 migration bullet, missing version-
  matrix 5.0.x row, missing README TOC entry, and a couple of style
  nits (sub-heading overpromise, orphan bullet).

Skipped (deferred to future PRs):
- README first-run tour mention.
- Admin guide HTTP kill-switch row in Failure-modes table.
- Terminal drag-drop trust-model precision update after plmbr#327.
- Cipher description nit in plmbr#293 (Fernet AES-128-CBC+HMAC, not
  AES-GCM).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants