From ebd03c987d15523d216a2155fa1b83210361410a Mon Sep 17 00:00:00 2001 From: Mark Shust Date: Wed, 3 Jun 2026 09:41:54 -0400 Subject: [PATCH] docs: widen sidebar, fix Claude Code install method, clarify MCP verification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs sidebar: override Starlight --sl-sidebar-width 18.75rem -> 19.75rem (single source of truth; --sl-content-width is independent, print stylesheet keeps its own 0px override). - ai-assisted-development/agents/claude-code.md: replace the deprecated `npm install -g @anthropic-ai/claude-code` + nonexistent `claude auth login` with the current native installer (`curl -fsSL https://claude.ai/install.sh | bash`) and first-run browser login / `/login`; expand the two .claude/settings.json keys (extraKnownMarketplaces.marko, enabledPlugins) with what each does and how Claude Code consumes them on folder-trust. - verification-checklist.md: Claude Code MCP is provided by the marko-mcp@marko plugin, not `claude mcp add` — verify via .claude/settings.json + `/mcp`, not `claude mcp list`. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/src/styles/custom.css | 5 +++++ .../agents/claude-code.md | 19 +++++++++++++------ .../verification-checklist.md | 3 ++- 3 files changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css index 613091ed..34a3d4b9 100644 --- a/docs/src/styles/custom.css +++ b/docs/src/styles/custom.css @@ -38,6 +38,11 @@ --sl-color-accent: #3498db; --sl-color-accent-high: #7ec8e3; + /* Left sidebar width (Starlight default is 18.75rem). Starlight derives the + whole page layout from this single variable, so overriding it here is the + only change needed — content width (--sl-content-width) is independent. */ + --sl-sidebar-width: 19.75rem; + --sl-color-white: #fcfcfc; --sl-color-gray-1: #e8e8e8; --sl-color-gray-2: #bcbcbc; diff --git a/packages/docs-markdown/docs/ai-assisted-development/agents/claude-code.md b/packages/docs-markdown/docs/ai-assisted-development/agents/claude-code.md index c52d76f7..f4eec383 100644 --- a/packages/docs-markdown/docs/ai-assisted-development/agents/claude-code.md +++ b/packages/docs-markdown/docs/ai-assisted-development/agents/claude-code.md @@ -7,8 +7,14 @@ description: Set up Marko's AI tooling with Anthropic Claude Code — CLAUDE.md ## Prerequisites -- Claude Code installed: `npm install -g @anthropic-ai/claude-code` -- Authenticated: `claude auth login` +- **Claude Code installed.** The recommended method is the native installer (no Node.js required, auto-updates in the background): + + ```bash + curl -fsSL https://claude.ai/install.sh | bash + ``` + + This covers macOS, Linux, and WSL; see the [Claude Code setup docs](https://docs.claude.com/en/docs/claude-code/setup) for Windows and other options. The legacy `npm install -g @anthropic-ai/claude-code` still works, but the native installer is now the preferred path. +- **Authenticated.** Run `claude` in your terminal and complete the browser sign-in on first launch (there is no separate `auth login` command — use `/login` inside a session to switch or manage credentials). Run `claude doctor` to confirm the installation type. - `marko/devai` installed (see [Installation](../installation/)) ## What devai:install writes @@ -29,12 +35,13 @@ The installer writes merged Marko guidelines to `AGENTS.md`. The `CLAUDE.md` fil `devai:install` writes (or merges into) `.claude/settings.json` with two keys: -- `extraKnownMarketplaces.marko` — registers the Marko plugin marketplace so Claude Code can fetch plugin metadata -- `enabledPlugins` — activates `marko-skills@marko`, `marko-lsp@marko`, and `marko-mcp@marko` +- `extraKnownMarketplaces.marko` — registers the Marko plugin marketplace so Claude Code can fetch plugin metadata. + + This is a named entry under Claude Code's `extraKnownMarketplaces` map. Its `source` tells Claude Code where to read the marketplace manifest (`.claude-plugin/marketplace.json`) from: when run inside the Marko monorepo the source is the local `packages/claude-plugins/plugins` path, and for external projects it is the `marko-php/marko` GitHub repo. Registering the marketplace does not install anything on its own — it only makes the `@marko` plugins discoverable. -When run inside the Marko monorepo the marketplace source points to the local `packages/claude-plugins/plugins` path; for external projects it points to the `marko-php/marko` GitHub repo. +- `enabledPlugins` — activates `marko-skills@marko`, `marko-lsp@marko`, and `marko-mcp@marko`. -On first trust of the project folder, Claude Code fetches and installs the three plugins automatically. + Each entry is a `plugin@marketplace` key set to `true`. Listing a plugin here tells Claude Code to install it from the registered marketplace and keep it enabled. On first trust of the project folder, Claude Code reads these entries and fetches the three plugins automatically — wiring the MCP server, the LSP server, and the scaffolding skills in a single step. `devai:install` only ever adds or replaces the `*@marko` entries, so any other plugins you have enabled are preserved. ### Plugins diff --git a/packages/docs-markdown/docs/ai-assisted-development/verification-checklist.md b/packages/docs-markdown/docs/ai-assisted-development/verification-checklist.md index acd51872..bdcea0b4 100644 --- a/packages/docs-markdown/docs/ai-assisted-development/verification-checklist.md +++ b/packages/docs-markdown/docs/ai-assisted-development/verification-checklist.md @@ -26,7 +26,8 @@ Choose one agent and verify its guidelines file: **Claude Code:** - [ ] `CLAUDE.md` exists in the project root and references `@AGENTS.md` - [ ] `AGENTS.md` exists in the project root and includes a `## Package Guidelines` section -- [ ] `claude mcp list` includes the `marko-mcp` server +- [ ] `.claude/settings.json` registers `extraKnownMarketplaces.marko` and enables the `marko-mcp@marko` plugin +- [ ] In Claude Code, run `/mcp` — the `marko-mcp` server appears (it is provided by the `marko-mcp@marko` plugin, not by `claude mcp add`) **Codex:** - [ ] `AGENTS.md` exists in the project root