docs alignment

Author: andrus

ai-plugin/README.md

@@ -31,7 +31,7 @@ The plugin assumes downstream **users of Cayenne** writing their own Java apps.
 
 ## Install
 
-**Cayenne 5.0+ only.** The MCP server ships with Cayenne 5.0. Skills that depend on it (`cayenne-cgen`, `cayenne-modeler`, `cayenne-reverse-engineer`) will not work against earlier Cayenne versions. The XML-editing, runtime, and query skills also target 5.0 idioms — for older Cayenne, this plugin is not the right tool.
+**Cayenne 5.0+ only.** The MCP server ships with Cayenne 5.0. Skills that depend on it (`cayenne-cgen`, `cayenne-modeler`, `cayenne-db-import`) will not work against earlier Cayenne versions. The XML-editing, runtime, and query skills also target 5.0 idioms — for older Cayenne, this plugin is not the right tool.
 
 The plugin is distributed from the Apache Cayenne GitHub repository: **https://github.com/apache/cayenne**. Inside Claude Code:
 
@@ -58,7 +58,7 @@ ai-plugin/
 ├── README.md                    # this file
 ├── skills/                      # auto-triggering workflows
 │   ├── cayenne-modeling/        # edit *.map.xml and cayenne-*.xml
-│   ├── cayenne-reverse-engineer/# import a DB schema (Modeler GUI)
+│   ├── cayenne-db-import/       # import a DB schema (Modeler GUI)
 │   ├── cayenne-cgen/            # regenerate Java classes via MCP
 │   ├── cayenne-modeler/         # open the GUI on a project
 │   ├── cayenne-runtime/         # bootstrap CayenneRuntime in an app

ai-plugin/references/mcp-tools.md

@@ -20,7 +20,7 @@
 
 The Cayenne MCP server (`cayenne-mcp-server` module) exposes Cayenne operations to AI agents over stdio.
 
-**Availability: Cayenne 5.0+ only.** The MCP server is a new component shipped alongside CayenneModeler starting with the 5.0 release. There is no MCP server for Cayenne 4.x or earlier — skills that depend on these tools (`cayenne-cgen`, `cayenne-modeler`, `cayenne-reverse-engineer`) cannot be used against pre-5.0 projects.
+**Availability: Cayenne 5.0+ only.** The MCP server is a new component shipped alongside CayenneModeler starting with the 5.0 release. There is no MCP server for Cayenne 4.x or earlier — skills that depend on these tools (`cayenne-cgen`, `cayenne-modeler`, `cayenne-db-import`) cannot be used against pre-5.0 projects.
 
 Setup is documented in `cayenne-mcp-server/README.md` at the repo root. Quick form for Claude Code:
 

…skills/cayenne-reverse-engineer/SKILL.md …plugin/skills/cayenne-db-import/SKILL.mdai-plugin/skills/cayenne-reverse-engineer/SKILL.md renamed to ai-plugin/skills/cayenne-db-import/SKILL.md ai-plugin/skills/cayenne-reverse-engineer/SKILL.md renamed to ai-plugin/skills/cayenne-db-import/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: cayenne-reverse-engineer
+name: cayenne-db-import
 description: "Use this skill whenever the user wants to import database schema metadata into a Cayenne DataMap — full-schema sync from a live DB. Trigger on phrases like 'reverse engineer the database', 'import the schema', 'generate a DataMap from my DB', 'sync the model with the database', 'add the new tables from the DB', 'import the customer table', 'pick up the latest schema changes', 'create entities from these tables', or any request that involves reading database metadata to populate or update a DataMap. This is for *full schema* or *bulk table* import; one-off a-la-carte entity additions belong in the cayenne-modeling skill. The skill runs reverse engineering directly via the `mcp__cayenne__dbimport_run` MCP tool when a DBConnector is already configured; otherwise it opens the CayenneModeler GUI via `mcp__cayenne__open_project` to configure the connection first."
 ---
 
@@ -21,7 +21,7 @@ description: "Use this skill whenever the user wants to import database schema m
 	specific language governing permissions and limitations
 	under the License.   
 -->
-# cayenne-reverse-engineer
+# cayenne-db-import
 
 Import a database schema into a Cayenne DataMap using the `mcp__cayenne__dbimport_run` MCP tool. If a DBConnector is already stored in preferences for the DataMap the import runs directly without any GUI interaction. When the connection has not been configured yet, the workflow launches CayenneModeler and walks the user through the dialog once to save the connection, then re-runs `dbimport_run`.
 

ai-plugin/skills/cayenne-modeler/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cayenne-modeler
-description: "Use this skill when the user explicitly wants to open CayenneModeler (the GUI) on a Cayenne project, or when the modeling task is inherently visual — reverse engineering (delegated to cayenne-reverse-engineer), bulk relationship layout, multi-entity visual refactoring. Trigger on phrases like 'open the Modeler', 'open in CayenneModeler', 'launch the GUI', 'edit visually', 'show me the project in the Modeler'. Do NOT trigger as a fallback for ordinary a-la-carte XML edits — those belong in the cayenne-modeling skill, which is faster and doesn't require the user to context-switch."
+description: "Use this skill when the user explicitly wants to open CayenneModeler (the GUI) on a Cayenne project, or when the modeling task is inherently visual — reverse engineering (delegated to cayenne-db-import), bulk relationship layout, multi-entity visual refactoring. Trigger on phrases like 'open the Modeler', 'open in CayenneModeler', 'launch the GUI', 'edit visually', 'show me the project in the Modeler'. Do NOT trigger as a fallback for ordinary a-la-carte XML edits — those belong in the cayenne-modeling skill, which is faster and doesn't require the user to context-switch."
 ---
 
 <!--
@@ -63,7 +63,7 @@ The tool spawns the Modeler asynchronously, then waits up to ~15 seconds for a s
 
 Once `open_project` returns `ok`, the user is in the GUI. From here, depending on intent:
 
-- **Reverse engineering**: that's the `cayenne-reverse-engineer` skill's job to walk them through. Do not duplicate that workflow here — just open and step out.
+- **Reverse engineering**: that's the `cayenne-db-import` skill's job to walk them through. Do not duplicate that workflow here — just open and step out.
 - **Visual layout / bulk editing**: tell the user what tab to navigate to (e.g., DataMap → ObjEntity for entity-level edits, DataMap → Class Generation for cgen config) and let them work. Don't try to script GUI actions.
 - **Just wanted to see the project**: nothing more to do.
 

ai-plugin/skills/cayenne-modeling/SKILL.md

@@ -81,7 +81,7 @@ If anything fails, fix it before reporting done.
 
 - **If you modified entities and the DataMap has a `<cgen>` block:** suggest invoking the `cayenne-cgen` skill to regenerate Java classes. Mention which entities are affected.
 - **If the user added a new entity and there's no Java class yet:** same — recommend `cayenne-cgen`.
-- **If the user is asking about a full DB sync** (importing many tables, syncing with a changed schema): hand off to `cayenne-reverse-engineer`. Do not try to script this via XML edits.
+- **If the user is asking about a full DB sync** (importing many tables, syncing with a changed schema): hand off to `cayenne-db-import`. Do not try to script this via XML edits.
 - **If the change is structurally messy** (bulk renaming relationships, visual graph rework): suggest the `cayenne-modeler` skill. Otherwise do not.
 
 ## Modeler coexistence

docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3.adoc

@@ -16,6 +16,6 @@
 
 include::part3/overview.adoc[]
 
-include::part3/installingMcpServer.adoc[]
+include::part3/installing.adoc[]
 
 include::part3/mcpTools.adoc[]

…nne-guide/part3/installingMcpServer.adoc …doc/_cayenne-guide/part3/installing.adocdocs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc renamed to docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installing.adoc docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installingMcpServer.adoc renamed to docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/installing.adoc

@@ -12,61 +12,64 @@
 // the specific language governing permissions and limitations under the
 // License.
 
-=== Installing the Cayenne MCP Server
 
-The MCP server is a self-contained, stdio-based process that the AI client launches on demand. It is bundled with the
-platform-specific CayenneModeler and requires Java 21 or later on the system `PATH`.
+=== Installing `apache-cayenne` Plugin (Claude Code)
+
+Install the `apache-cayenne` plugin with Cayenne-specific skills under Claude Code:
+
+[source,bash]
+----
+/plugin marketplace add apache/cayenne
+/plugin install apache-cayenne@apache-cayenne
+/reload-plugins
+----
+
+The plugin adds skills for DataMap editing, class generation, reverse engineering, query writing, and runtime setup.
+The skills work best with the MCP server present (see the next chapter).
 
-==== Finding the JAR
+=== Installing the Cayenne MCP Server
 
-As mentioned above, the MCP server jar is a part if the CayenneModeler download (available at
-https://cayenne.apache.org/download/). Its location depends on the install format:
+The MCP server is a self-contained, stdio-based process that the AI agent launches on demand. It works with most agents
+(not only Claude). The MCP server is bundled with the platform-specific CayenneModeler and requires Java 21 or
+later on the system `PATH`. So to get it, first download the Modeler at https://cayenne.apache.org/download/ .
 
-===== macOS
+MCP runnable jar is `CayenneMCPServer.jar`. Its location is OS-dependent (you will need this location in the next step):
 
+Mac:
 [source]
 ----
 # <install-dir> is typically "/Applications", but it can be any other directory
 <install-dir>/CayenneModeler.app/Contents/Resources/mcp/CayenneMCPServer.jar
 ----
 
-===== Windows
-
+Windows:
 [source]
 ----
 <install-dir>\bin\CayenneMCPServer.jar
 ----
 
-===== Linux / cross-platform
-
+Linux / cross-platform:
 [source]
 ----
 <install-dir>/bin/CayenneMCPServer.jar
 ----
 
-==== Configuring AI clients
-
-The server communicates over stdio and is launched on demand by the client. In the snippets below, replace
-`/path/to/CayenneMCPServer.jar` with the actual jar path from the previous section.
-
-===== Claude Code
+When installaing the MCP, replace `/path/to/CayenneMCPServer.jar` mentioned in the instructions with the actual jar path:
 
-By default `claude mcp add` registers the server for the current project only. Use `--scope user` to make it available
-across all projects for your OS user:
+==== Claude Code
 
 [source,bash]
 ----
-# Current project only
-claude mcp add cayenne -- java -jar /path/to/CayenneMCPServer.jar
-
-# All projects for the current user
+# Register the MCP server (--scope user makes it available across all projects)
 claude mcp add cayenne --scope user -- java -jar /path/to/CayenneMCPServer.jar
+
+# Verify it is connected
+claude mcp list
 ----
 
-===== Cursor
+==== Cursor
 
 Edit `~/.cursor/mcp.json` (global, all projects) or `.cursor/mcp.json` in your project (per-project):
-
 [source,json]
 ----
 {
@@ -79,8 +82,7 @@ Edit `~/.cursor/mcp.json` (global, all projects) or `.cursor/mcp.json` in your p
 }
 ----
 
-===== Codex
-
+==== Codex
 Add a `[mcp_servers.cayenne]` entry to `~/.codex/config.toml`:
 
 [source,toml]

docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/mcpTools.adoc

@@ -14,7 +14,12 @@
 
 === MCP Tools
 
-The server exposes three tools. Your agent will discover them on its own, but it is useful to understand the capabilities and possible prompts. All tools operate on a Cayenne project descriptor (a `cayenne-*.xml` file) and take absolute paths - agents should resolve relative paths against the current workspace before invoking.
+The server exposes three tools. Your agent will discover them on its own, but it is useful to understand the
+capabilities and possible prompts. All tools operate on a Cayenne project descriptor (a `cayenne-*.xml` file) and take
+absolute paths — agents should resolve relative paths against the current workspace before invoking.
+
+If you are using the `apache-cayenne` Claude Code plugin, its skills (`cayenne-cgen`, `cayenne-modeler`, `cayenne-db-import`)
+call these tools automatically. You can verify the server is available with `claude mcp list` — look for an entry named `cayenne`.
 
 ==== open_project
 
@@ -70,12 +75,12 @@ ____
 ==== dbimport_run
 
 Runs Cayenne reverse engineering (dbimport) for a single DataMap inside the project.
-The tool reads the JDBC connection from the DBConnector that CayenneModeler stored in preferences when the user last ran the reverse-engineering dialog for this DataMap.
+The tool reads the JDBC connection from CayenneModeler preferences on the local machine (the agent doesn't see the credentials).
 If the DataMap has a `<reverse-engineering>` block its filters are applied; otherwise the full database schema is imported.
 The DataMap XML is rewritten on disk with the merged schema, and a JSON summary of what changed is returned.
 
-JDBC credentials are not passed as arguments — they come from CayenneModeler preferences.
-If no connection has been saved yet (`dbconnector_not_configured` error), open the project in the Modeler with `open_project`, run the dialog once to save the connection, then call `dbimport_run` again.
+If no connection has been saved yet (`dbconnector_not_configured` error), open the project in the Modeler with
+`open_project`, run the dialog once to save the connection, then call `dbimport_run` again.
 
 .Parameters
 [cols="1,1,3", options="header"]

docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part3/overview.adoc

@@ -16,4 +16,9 @@
 
 AI coding agents such as Claude Code, Cursor, etc. can read and write Cayenne projects like any other Java codebase. For day-to-day API work — writing queries, manipulating an `ObjectContext`, etc. — you don't need anything Cayenne-specific. Prompt the agent the way you would for any other project.
 
-The Cayenne MCP (Model Context Protocol) server is what makes the agent _Cayenne-aware_ beyond plain source editing. It is a small stdio-based process that the AI client launches on demand and exposes a focused set of tools for operating on a Cayenne project descriptor. This chapter walks you through installing the server and explains the available tools.
+Two additional elements make the agent _Cayenne-aware_ beyond plain source editing:
+
+* MCP server — a small stdio-based process the agent launches on demand, exposing tools for class generation, DB import, and opening CayenneModeler. Works with any MCP-compatible client (Claude Code, Cursor, Codex, etc.).
+* `apache-cayenne` Claude Code plugin — a Claude Code-specific extension that bundles pre-built skills for DataMap editing, query writing, runtime setup, and more. The skills detect the MCP server at runtime; 
+
+Both elements are independent but work best together. This chapter walks you through installing both and explains the available MCP tools.