Skip to content

docs: AI-install harness matrix, MCP registration reference, akka.ai entry - #1877

Merged
ennru merged 10 commits into
akka:mainfrom
TylerJewell:docs/ai-install-playbook-support
Sep 16, 2026
Merged

ennru merged 10 commits into
akka:mainfrom
TylerJewell:docs/ai-install-playbook-support

Conversation

@TylerJewell

Copy link
Copy Markdown
Contributor

Background

Akka's website has grown busy enough that the Get-Started sequence is hard to find. doc.akka.io documents 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.io will become:

Ask your AI to install Akka from akka.ai.

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 via akka specify init --agent X / CLI + AGENTS.md + manual MCP) with a row for each harness. Empty-directory guidance for /akka:setup and akka 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 per reference/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.json under context_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 runs akka mcp serve.
  • sdk/nav.adoc — new nav entry for register-mcp under "Building with AI".
  • ROOT/pages/index.adoc — added https://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

  • Does not touch PR docs: Aid AI harnesses to properly figure out how to install Akka Specify #1876's two files (ai-coding-assistant.adoc, spec-your-first-agent.adoc). Merges cleanly in either order.
  • Uses hardcoded GitHub URLs for the AGENTS.md attachment link per docs/bin/verify-include-paths.sh behavior.
  • Vale not run locally (binary not installed); CI is the enforcement point for the new vocabulary terms.

Sibling PRs (AI-install rollout)

The three PRs are safe to merge independently. This PR describes the shipped CLI state; additional per-harness --agent profiles 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

TylerJewell and others added 6 commits September 13, 2026 07:43
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>
TylerJewell and others added 2 commits September 13, 2026 08:42
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
ennru merged commit 0312447 into akka:main Sep 16, 2026
11 checks passed
@ennru ennru added the docs-publish Marks a documentation PR for manual publishing. label Sep 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Automatic cherry-pick to docs-current failed for 0312447efc8f47efbd28b5fe58b961ed7c3edd52 (run 35108729846). Skipped — resolve manually or re-label after fixing.

@github-actions

Copy link
Copy Markdown
Contributor

Automatic cherry-pick to docs-current failed for 0312447efc8f47efbd28b5fe58b961ed7c3edd52 (run 35108792632). Skipped — resolve manually or re-label after fixing.

@ennru ennru added the docs-published PR was cherry-picked for publishing. label Sep 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-publish Marks a documentation PR for manual publishing. docs-published PR was cherry-picked for publishing. documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants