Repository navigation
Docs: high-priority page rewrites for positioning alignment - #1453
Merged
Merged
Conversation
5 tasks
TylerJewell
force-pushed
the
docs/high-priority-rewrites
branch
2 times, most recently
from
March 25, 2026 22:12
392b930 to
a79e1ef
Compare
New top-level entry point framing the three barriers (Production Gap, Liability, Specialist Trap) and three dimensions (Reliability, Risk Control, Repeatability). Includes competitive comparison table and links to external content via the link registry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> # Conflicts: # docs/src/modules/ROOT/pages/why-akka.adoc
Brief platform intro covering full-stack positioning, key differentiators, service tiers (Fast Prod through Sovereign Cloud), and application types with links to akka.io product pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New Understanding page explaining why bolt-on governance fails for agentic AI (immutable records, human intervention, authorization capture, PII scrubbing) and how Akka embeds governance in the runtime. Covers EU AI Act alignment and compliance certifications. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Update antora.yml nav order: ROOT (Why/What/Who) -> Tutorials -> Understanding -> Developing -> Operating -> Resources -> Reference - ROOT nav.adoc now includes Why Akka, What is Akka, Who Uses Akka - New resources-nav.adoc for the Resources top-level section - Rewrite homepage: lead with positioning (three barriers/dimensions), SDD-first tutorial ordering, Governance & Runtime in Understanding, AAO leading Operating, Resources section added Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add: Anthropic, biopharma, decisioning, Doctolib, explainability, Hanafee, infosec, Llaama, Manulife, QCon, regionalized, reputational, Swiggy, Telecom, Tubi to the Vale spelling accept list. These are proper nouns, industry terms, and customer names used in new documentation pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Update antora.yml nav order: ROOT (Why/What/Who) -> Tutorials -> Understanding -> Developing -> Operating -> Resources -> Reference - ROOT nav.adoc now includes Why Akka, What is Akka, Who Uses Akka - New resources-nav.adoc for the Resources top-level section - Rewrite homepage: lead with positioning (three barriers/dimensions), SDD-first tutorial ordering, Governance & Runtime in Understanding, AAO leading Operating, Resources section added Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 from "Project structure" to "Architecture". Add page metadata attributes. Add Overview section connecting to the three dimensions (Reliability via runtime, Risk Control via governance, Repeatability via developer experience). Fix voice to second-person. Add See Also with external links. All existing technical content preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata with governance personas. Add Overview connecting guardrails to runtime-embedded governance and EU AI Act compliance. Fix voice to second-person. Reorganize under clearer subsections. Add See Also with governance and trustworthy AI links. All existing code examples preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "Data Sanitization". Add page metadata with governance personas. Frame PII scrubbing as runtime-level governance property with EU AI Act right-to-explanation connection. Fix voice to second-person. Add See Also section. All code examples preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add Overview framing SDD as primary approach. Lead with 6-step SDD lifecycle connected to Repeatability dimension. Move manual development workflow into TIP.manual admonition callout. Fix voice to second-person. Add See Also with SDD links. All existing component descriptions and technical content preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata for operator personas. Add Overview section. Add service tiers (Fast Prod, Day 2 Ops, Business Continuity, Sovereign Cloud). Add Reliability section with availability guarantees. Fix voice to second-person. Add See Also with demo links. All existing operational content preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add 19 new entries: A2A, ACP, Agentic AI, AI Agent, Constitution, EU AI Act, Guardrails, LLM, MCP, Production Gap, Reliability, Repeatability, Risk Control, Sanitizer, SDD, Specialist Trap, Spec-Driven Development, Three Barriers, Three Dimensions. All 25 original entries preserved. New entries include cross-references linking related terms. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "Agents". Add page metadata with component-type. Add Overview with when-to-use, when-not-to-use, and component relationships. Rename "Skeleton" to "Basic Agent Structure". Fix voice to second-person throughout. Add See Also with AI concepts, guardrails, memory, and protocol links. All code examples and include directives preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "AI Agents". Add page metadata. Add Overview with component relationships. Add three barriers section (Production Gap, Liability, Specialist Trap) and three dimensions section (Reliability, Risk Control, Repeatability). Fix voice to second-person. Add See Also with external links. All existing content preserved including video embed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Flip the TIP to present SDD as the recommended approach, with the manual Java walkthrough as secondary for understanding components under the hood. Add See Also with SDD, planner tutorial, and Akkademy links. All existing tutorial content, code examples, and images preserved. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add Overview with when-to-use guidance. Lead installation with AI Marketplace plugin as primary path, CLI fallback in TIP.manual admonition. Fix voice to second-person throughout. Add See Also with external links. All existing technical content preserved (maturity levels, specify/clarify/ plan/tasks/implement/build workflow, command table). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Lowercase non-proper-noun words in page title and all xref labels across sanitization page, governance page, and who-uses-akka page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace separate Package and Deploy sections with a single section describing two paths: direct deployment to Akka via CLI/Console, or GitOps via CI/CD pipelines. Add CI/CD integration link. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Lowercase H1 and xref label in concepts index page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Akka component names (Endpoints, Agent, Consumer, etc.) are proper nouns and should be capitalized. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Service tiers are sales content and do not belong in SDK docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove entries that are sales/positioning only: EU AI Act, Production Gap, Specialist Trap, Risk Control, Three Barriers, Three Dimensions. Fix capitalization: "Component ID" (not "id"), "Workflow step" (not "Step"). Update cross-references in remaining entries that pointed to removed entries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These are positioning/sales content. The AI Agents concepts page should focus on technical concepts: tokens, prompts, memory, orchestration, evaluation. Updated page-summary accordingly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the platform graphic, "Developers create..." paragraph, and product table from the tutorial introduction. These belong in conceptual/overview pages, not a hands-on tutorial. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rewrite Getting Started section with three-tier installation: 1. Primary: AI Marketplace plugin (4 steps with commands) 2. Alternative: Clone plugin from Akka repository 3. Fallback: akka specify init <dir> (in TIP.manual admonition) When plugin is installed, /akka-specify:setup handles environment setup (CLI, Java, Maven, Akka download token). Updated "Using Akka specify" section to clarify it describes fallback behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Java/Maven-first approach with three-step quickstart: install Akka plugin from marketplace, run /akka-specify:setup, run first specification. CLI fallback in admonition. Hands-on Java tutorials moved to secondary section. Component names capitalized throughout. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three-tier installation: marketplace (primary), clone from https://github.com/akka/ai-marketplace (alternative), CLI akka specify init (last resort). Clone instructions show how to add the cloned directory as a local marketplace in Claude Code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Consolidate marketplace add, plugin install, and reload into one code block. Clone-from-repo is now a TIP inline rather than a separate section. Two clean steps: install plugin, run setup. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove starthere.adoc as separate nav entry — it was a duplicate of index.adoc with outdated prerequisites content. Replace with redirect to index.adoc. Nav now has single "Tutorials" entry pointing to index.adoc. Spec-first agent listed before hello world. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Getting Started / Tutorials page now appears in two places in the nav: as a top-level "Getting started" entry after Why Akka, and as "Tutorials" in its own section with sub-pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Include explicit git clone instructions for ai-marketplace repo as alternative to marketplace add. Reword CLI fallback as "No plugin capability for your AI assist?" pointing to SDD page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
You are already on this page — no reminder needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Plugin name changed: akka-specify@ai-marketplace -> akka@ai-marketplace Skill prefix changed: /akka-specify: -> /akka: Updated in Getting Started, SDD page, and spec-first tutorial. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace claim of immediate running service with accurate description of what happens: Akka builds a specification and guides you through plan, implementation, build, and test steps. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Consolidate all fallback/alternative install guidance together in Step 1 before moving on to Step 2. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move spec-first greeting Agent into its own section with description of SDD command workflow. Hands-on tutorials now contain only the manual Java tutorials. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add width=100% to Spec-driven and Build your first Agent tables so they match the width of multi-row tables below. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the platform graphic, descriptive paragraphs, and product table from the tutorial introduction. Same cleanup as the hello world tutorial — these belong in conceptual pages, not tutorials. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prerequisites now list only AI coding assistant and OpenAI key. Java, Maven, curl, Git, and Akka CLI moved to "Additional prerequisites for those without an AI marketplace" subsection since the plugin installs these automatically. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The plugin is the primary path, not optional. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Unicode box-drawing character tables in code blocks with proper AsciiDoc tables for consistent HTML rendering. Affects plan output, task summary, implementation summary, and build results sections. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove "Without the plugin" title from TIP admonition. Remove Akka Code Init Demo from See Also — not relevant to SDD. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…utorial" This reverts commit de352fe.
Replace <<_package_service>> and <<_deploy>> with <<_package_and_deploy>> to match the merged section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ennru
force-pushed
the
docs/high-priority-rewrites
branch
from
March 26, 2026 20:58
a79e1ef to
31e0bd2
Compare
ennru
approved these changes
Mar 26, 2026
ennru
left a comment
Contributor
There was a problem hiding this comment.
Good improvements in this PR.
LGTM.
Comment on lines
-19
to
-22
| include::ROOT:partial$local-dev-prerequisites.adoc[] | ||
| * Git | ||
| * An AI coding assistant like Claude Code to build and implement the specification | ||
| * xref:quick-install-cli.adoc[Akka CLI] (_installed automatically if you use the Akka Claude Code plugin_) |
Contributor
There was a problem hiding this comment.
IIUC the Claude plugin does NOT install Java and Maven
| If you were able to create and build an empty project, then you're all set and you can continue on to the tutorials. | ||
|
|
||
|
|
||
| This page has moved. See xref:getting-started:index.adoc[Tutorials]. |
Contributor
There was a problem hiding this comment.
We can add a renamed tag to that page.
|
|
||
| This configures your environment — ensuring the Akka CLI is installed, Java and Maven are available, and your Akka download token is properly configured. Once setup completes, you are ready to start building. | ||
|
|
||
| NOTE: Not using Claude Code? Akka supports 30 different AI assist tools. Visit https://doc.akka.io[doc.akka.io] for installation instructions for your tool. |
Contributor
There was a problem hiding this comment.
This link to doc.akka.io doesn't make sense.
This was referenced Mar 27, 2026
ennru
pushed a commit
that referenced
this pull request
Mar 27, 2026
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.
Summary
Depends on #1452 (infrastructure and structure PR).
10 high-priority page rewrites to align with revised positioning (Reliability, Risk Control, Repeatability), SDD-first approach, and writing standards:
All pages: second-person voice, page metadata attributes, See Also sections with external links, all existing code examples preserved.
Test plan
🤖 Generated with Claude Code