Repository navigation
docs: AI-install harness matrix, MCP registration reference, akka.ai entry - #1877
Merged
Merged
Conversation
Adds the getting-started/AI-install docs the akka.ai playbook depends on: - Harness support matrix in set-up-dev-env.adoc grouping harnesses by install path (plugin bundle, `akka specify init --agent <harness>`, or CLI + AGENTS.md + manual MCP fallback), plus the current unsupported list (Windsurf, Gemini Code Assist, Tabnine, Codeium, and the four discontinued surfaces). - Empty-directory contract callout: `/akka:setup` and `akka specify init` both scaffold into the current directory and expect it to be empty. - New sdk:register-mcp.adoc with canonical MCP registration snippets for Zed, Aider, Sourcegraph Cody, Claude.ai chat, and a generic stdio harness. Linked from the sdk nav. - akka.ai entry on the docs landing page under "More". - Vale vocabulary additions for the new harness names. The AGENTS.md template already lives at docs/src/modules/ROOT/attachments/AGENTS.md and is published at doc.akka.io/sdk/_attachments/AGENTS.md; the matrix references it there. The CLI install page (operations/cli/installation.adoc) already covers Homebrew, curl, and winget so no duplicate `/install` page is added. Antora build not run (Docker daemon not available in this environment). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Prior commit ran `sort -u` on accept.txt, producing a 231/255-line churn diff for what is really 24 new entries. Restore the file's existing order and insert each new harness name at its case-insensitive alphabetical position. Same 24 terms; +24/-0 diff instead of +231/-255. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…markers Harness support matrix: - Split the JetBrains/VS/Xcode/Neovim Copilot row: vs-copilot and copilot-agent are shipped profiles; jetbrains-copilot, xcode-copilot, and nvim-copilot move to the manual-MCP fallback with an explicit "profile pending" note (no per-project MCP path documented by the vendor today). - Kilo, Cline, Replit likewise move to the manual-MCP fallback with a "profile pending" note — each is blocked on a documented harness path the vendor has not published. - NOTE below the matrix now lists the 12 shipped `--agent` profiles explicitly and names the 6 pending ones with the reason. Register the Akka MCP server: - Zed: correct the snippet nesting (flat command/args under context_servers.akka, not a nested command object) and drop the VERIFY marker (context_servers is stable in current Zed). - Aider: drop the VERIFY on a "recommend a bridge" line — no canonical bridge exists today; the section documents both workaround patterns as they stand. - Cody: drop the VERIFY marker and the admitted-unverified config path; link to Sourcegraph's own Cody MCP documentation as the current source of truth for the settings location. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Second docs-review pass. Blockers were: (1) matrix listed CLI-init commands that don't wire the harness fully, (2) NOTE overstated which profiles ship, (3) contradiction between the matrix (--agent zed) and register-mcp.adoc (Zed as manual-fallback). - Split the CLI-init rows honestly: only the 6 profiles that write the harness's real per-project rules AND MCP paths stay as CLI init (`vs-copilot`, `factory`, `roo`, `devin`, `trae`, `junie`). The four alias-to-AGENTS.md profiles (`warp`, `jules`, `zed`, `copilot-agent`) move to CLI + AGENTS.md + manual MCP, each with a one-line note saying why (harness reads AGENTS.md but MCP path is elsewhere or UI-managed). - The Zed row now points at register-mcp.adoc, matching that page's Zed section — contradiction resolved. - NOTE rewritten to name the stable CLI profiles (`cursor`, `vscode-copilot`, `generic`), surface `--agent generic` as the reader-visible fallback, and be honest that the additional profiles require the paired CLI release rather than claiming they ship today. - "Any harness not listed" row now describes the fallback outcome instead of saying "same as Aider". Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Fourth docs-review pass. Root cause of the recurring blockers: I was documenting the state the AI-install initiative reaches after the paired akka/cli PR ships, not the state the shipped CLI has today. The generated CLI reference (akka_specify_init.adoc) is the source of truth for what `--agent` values work now — `claude-code`, `cursor`, `vscode-copilot`, `generic` — and any other value errors. Collapsed all the aspirational per-harness rows (`vs-copilot`, `factory`, `roo`, `devin`, `trae`, `junie`, `warp`, `jules`, `zed`, `copilot-agent`, and the six pending ones) into one row that names those harnesses and points at `akka specify init --agent generic` + xref:sdk:register-mcp.adoc as the honest install path today. When per-harness profiles ship in the CLI, a follow-up doc commit adds each as its own CLI-init row. Also: - Dropped the `akka specify init --version` instruction (that flag does not exist on the init subcommand). - Aider, Sourcegraph Cody, Zed and Claude.ai chat stay as named rows because they call out specific things a reader needs to know (Aider's lack of native MCP; Cody's shifting settings path; Zed's `.zed/settings.json`; Claude.ai's admin-gated MCP). - Zed classification is now consistent with `register-mcp.adoc` (both put Zed in the manual-fallback path). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Empty-directory precondition softened: the generated CLI reference for `akka specify init` doesn't guarantee empty-directory behavior, so drop the "expect that directory to be *empty*" phrasing and keep only the actionable "create a fresh folder so nothing is overwritten" guidance. - Cursor row Path column now reads "Plugin or CLI init" (both are valid; the target column already lists both). - GitHub Copilot (VS Code) row Path column corrected to "CLI init" — the install target is `akka specify init --agent vscode-copilot`, so the "Plugin" categorization was wrong. The Vale vocabulary spot-check nit (Cascade, Fleet, Factory, Void, Roo as generic English) is deferred to CI, which runs Vale against the current vocabulary. Local runs aren't possible without the Vale binary. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Vale flagged `mcp` inside the xref `akka_mcp_serve.adoc[akka mcp serve]` in register-mcp.adoc. The uppercase form appears in body prose and the lowercase form appears inside filenames and JSON keys; both are the same acronym. Added `[Mm]cp` as a regex vocabulary entry so either case is accepted. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
ennru
approved these changes
Sep 14, 2026
Contributor
|
Automatic cherry-pick to |
Contributor
|
Automatic cherry-pick to |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background
Akka's website has grown busy enough that the Get-Started sequence is hard to find.
doc.akka.iodocuments several installation techniques and we have simplified them substantially, but visitors are still struggling to land on the right page.What we are doing. Instead of directing humans to a docs page, we give a single instruction to their AI coding assistant, and the AI handles the rest — regardless of which harness they run. The CTA on
akka.iowill become:The user pastes "install Akka from akka.ai" into their harness. Their AI fetches the playbook at
akka.ai/, identifies the harness, picks the right install path, previews the whole plan to the user, then walks them through it with a consent prompt at every step.What this PR changes
Docs-only. Six additions across five files (+~170 lines total):
getting-started/pages/set-up-dev-env.adoc— new "harness support matrix" section: three install paths (Plugin / CLI init viaakka specify init --agent X/ CLI + AGENTS.md + manual MCP) with a row for each harness. Empty-directory guidance for/akka:setupandakka specify init. Explicit unsupported list (Windsurf/Cascade, Gemini Code Assist, Tabnine, Codeium, plus the discontinued four). The matrix describes only what the shipped Akka CLI supports today perreference/pages/cli/akka-cli/akka_specify_init.adoc(claude-code,cursor,vscode-copilot,generic); the "Any other harness with AGENTS.md support" row covers the roadmap harnesses (Factory, Devin, Junie, Roo, Trae, Warp, Zed, Jules, Visual Studio 2022 Copilot, GitHub Copilot coding agent, ...) via--agent generic+ xref to the MCP registration page.sdk/pages/register-mcp.adoc— new reference page: canonical MCP-registration snippets for Zed (.zed/settings.jsonundercontext_servers), Aider (no native MCP; two workaround patterns), Sourcegraph Cody (link to Cody's own MCP docs for the current settings path), Claude.ai chat with Projects (admin-gated), and a generic-stdio pattern. Every snippet runsakka mcp serve.sdk/nav.adoc— new nav entry forregister-mcpunder "Building with AI".ROOT/pages/index.adoc— addedhttps://akka.ai[akka.ai]link on the docs landing page's "More" section with an xref to the harness support matrix anchor.styles/config/vocabularies/Akka/accept.txt— 24 new harness names (Aider, Antigravity, Cascade, Cline, Cody, Codeium, Devin, Droid, Factory, Fleet, Jules, Junie, Kilo, Kiro, Neovim, Replit, Roo, Sourcegraph, Tabnine, Trae, Void, Warp, Windsurf, Zed) inserted at their alphabetical positions — no re-sort churn.Coordination
ai-coding-assistant.adoc,spec-your-first-agent.adoc). Merges cleanly in either order.docs/bin/verify-include-paths.shbehavior.Sibling PRs (AI-install rollout)
docs: multi-manifest repo layout + tag-pin install contract— docs: multi-manifest repo layout + tag-pin install contract ai-marketplace#36feat(sdd): agent-neutral AGENTS.md, verified --agent profiles— https://github.com/akka/cli/pull/193The three PRs are safe to merge independently. This PR describes the shipped CLI state; additional per-harness
--agentprofiles land as the paired CLI PR ships them, at which point a follow-up doc PR expands the matrix.Reviewed
Four rounds of
/akka-pr-review(independent read-only agent). Verdict: READY TO PUSH; the final round returned nits only, and a follow-up nit-fix commit addressed the categorization slip on the Cursor/VS Code Copilot rows and softened the empty-directory precondition.🤖 Generated with Claude Code