update docs, introduce home page for documentation, bump snapshot version

Author: MoonWorm

docs/_data/navigation.yml

@@ -1,6 +1,6 @@
 main:
   - title: "Documentation"
-    url: /introduction/
+    url: /documentation/
   - title: "Blog"
     url: /blog/
   - title: "Contact"
@@ -19,6 +19,10 @@ docs:
         url: /write-operations/
       - title: "Request/Response Examples"
         url: /request-response-examples/
+  - title: "AI-Assisted Development"
+    children:
+      - title: "AI-Assisted Development"
+        url: /ai-assisted-development/
   - title: "Framework Internals"
     children:
       - title: "Project Structure"

docs/ai-assisted-development.md

@@ -0,0 +1,73 @@
+---
+title: "AI-Assisted Development"
+permalink: /ai-assisted-development/
+---
+
+JsonApi4j is built to work well with AI coding agents. The repository ships two first-class,
+version-controlled assets — one for people **building apps with** the framework, and one for people
+**contributing to** it — so your AI assistant has accurate, framework-specific context instead of
+guessing from generic Java knowledge.
+
+### Building apps with the framework — the Claude Code plugin
+
+The project publishes an official **[Claude Code](https://claude.com/claude-code) plugin** that bundles
+the `jsonapi4j` skill. Once installed, your agent knows how to model and build a JSON:API service the
+framework's way.
+
+Install it from any project that depends on JsonApi4j:
+
+```text
+/plugin marketplace add MoonWorm/jsonapi4j
+/plugin install jsonapi4j@jsonapi4j
+```
+
+The first command registers this repository as a plugin marketplace; the second installs the plugin
+from it. The skill **auto-activates** whenever you work in a codebase that uses JsonApi4j — detected
+from imports under `pro.api4.jsonapi4j`, the `@JsonApiResource` / `@JsonApiRelationship` /
+`@JsonApiResourceOperation` annotations, or a `/jsonapi` root path.
+
+It covers the full surface a typical service needs:
+
+- **Resources, relationships, and operations** — the three-part anatomy, lightweight relationship refs
+  vs. full DTOs, and the composite operation interfaces.
+- **Compound documents** — `?include=` resolution, `cd.mapping`, and multi-hop traversal.
+- **Performance** — N+1-safe relationship resolution, batch operations, and `filter[id]` batching.
+- **Validation, access control, and configuration** — the fluent validators, per-field authorization,
+  and the `jsonapi4j.*` properties.
+- **Testing** — black-box RestAssured patterns, including the port setup that compound-document tests
+  require.
+
+The skill uses progressive disclosure — a lean entry point plus on-demand reference files — and points
+at real, runnable code in the framework's [sample apps](https://github.com/MoonWorm/jsonapi4j/tree/main/examples)
+and the pages on this site. You don't need to check out the framework source: add the dependency, install
+the plugin, and build in your own repository.
+
+### Contributing to the framework — AGENTS.md
+
+For working **on** JsonApi4j itself, the repository root carries a committed
+[`AGENTS.md`](https://github.com/MoonWorm/jsonapi4j/blob/main/AGENTS.md) (with a nested
+[`docs/AGENTS.md`](https://github.com/MoonWorm/jsonapi4j/blob/main/docs/AGENTS.md) for documentation-site
+work). [`AGENTS.md`](https://agents.md/) is an emerging cross-tool standard, so the same context is
+picked up by Claude Code, Cursor, GitHub Copilot, Codex, and other agents.
+
+It is a lean router, not a manual — it gives an agent the few things it can't cheaply derive:
+
+- **Build, test, and verify commands** — including the policy of keeping the shared test suite green
+  across all three sample apps (Spring Boot, Quarkus, Servlet).
+- **A module map** and the dependency direction.
+- **Load-bearing conventions** — commit format, the extension points (overridable default beans, the
+  plugin SPI), and a handful of non-obvious gotchas.
+- **Pointers** to the deeper docs, so it knows where to read more.
+
+### Why it matters
+
+The value isn't "the AI writes your API for you." It's that an agent equipped with this context produces
+**consistent, spec-compliant code that follows the framework's idioms** — relationship refs instead of
+heavy DTOs, includes wired through `cd.mapping`, N+1-safe resolution, and the correct test setup —
+rather than plausible-looking Java that fights the framework. Less review friction, fewer subtle bugs.
+
+### Links
+
+- Plugin source: [`claude-code-plugin/`](https://github.com/MoonWorm/jsonapi4j/tree/main/claude-code-plugin)
+- Contributor context: [`AGENTS.md`](https://github.com/MoonWorm/jsonapi4j/blob/main/AGENTS.md)
+- Repository: [github.com/MoonWorm/jsonapi4j](https://github.com/MoonWorm/jsonapi4j)

docs/documentation.md

@@ -0,0 +1,17 @@
+---
+title: "Documentation"
+permalink: /documentation/
+layout: single
+sidebar:
+classes: wide
+---
+
+Welcome to the JsonApi4j documentation. New here? Start with the
+**[Quick Start Guide](/getting-started/)**. Otherwise, browse the full table of contents below.
+
+{% for group in site.data.navigation.docs %}
+## {{ group.title }}
+
+{% for item in group.children %}- [{{ item.title }}]({{ item.url }})
+{% endfor %}
+{% endfor %}

docs/index.md

@@ -7,6 +7,8 @@ header:
   actions:
     - label: "Get Started"
       url: /getting-started/
+    - label: "Browse Docs"
+      url: /documentation/
     - label: "View on GitHub"
       url: "https://github.com/MoonWorm/jsonapi4j"
     - label: "Maven Central"
@@ -36,6 +38,17 @@ feature_row_dx:
     excerpt: "No JPA or Hibernate required. Works with SQL, NoSQL, REST clients, in-memory stores, or any data source you bring."
   - title: "Parallel Execution"
     excerpt: "Relationship resolution, compound document fetching, and batch operations run concurrently. Supports virtual threads (Project Loom) for maximum throughput."  
+
+feature_row_ai:
+  - title: "Official Claude Code Plugin"
+    excerpt: "Install the plugin and your AI agent instantly knows how to design resources, relationships, operations, compound documents, validation, and tests — right in your own project."
+    url: /ai-assisted-development/
+    btn_label: "Learn More"
+    btn_class: "btn--primary"
+  - title: "Works With Any AI Tool"
+    excerpt: "A committed `AGENTS.md` gives Claude Code, Cursor, GitHub Copilot, and Codex the same project context — build commands, conventions, and module map."
+  - title: "Knows the Idioms"
+    excerpt: "Not generic Java scaffolding — agents follow framework patterns: lightweight relationship refs, N+1-safe includes, `cd.mapping`, and the right testing setup."
 ---
 
 ## Choose Your Stack
@@ -74,6 +87,13 @@ feature_row_dx:
 
 {% include feature_row id="feature_row_dx" %}
 
+<div class="dark-band" markdown="0">
+  <h2>Built to Pair With Your AI Agent</h2>
+  <p class="dark-band__subtitle">An official Claude Code plugin and a cross-tool <code>AGENTS.md</code> — so your AI assistant builds spec-compliant APIs the framework's way. <a href="/ai-assisted-development/">Learn more →</a></p>
+</div>
+
+{% include feature_row id="feature_row_ai" %}
+
 <div class="pipeline-band" markdown="0">
   <h3>Request Processing Pipeline</h3>
   <p>Every incoming API request flows through a well-defined <strong>processing pipeline</strong> — from data retrieval through relationship resolution to final document composition. At each stage, registered <a href="/plugins/">plugins</a> can inspect, mutate, or short-circuit the request using the Visitor pattern.</p>

examples/pom.xml

@@ -19,7 +19,7 @@
     </modules>
 
     <properties>
-        <jsonapi4j.version>1.8.5</jsonapi4j.version>
+        <jsonapi4j.version>1.8.6-SNAPSHOT</jsonapi4j.version>
 
         <jakarta.servlet-api.version>6.1.0</jakarta.servlet-api.version>
 

pom.xml

@@ -52,7 +52,7 @@
 
     <properties>
         <!--project revision-->
-        <revision>1.8.5</revision>
+        <revision>1.8.6-SNAPSHOT</revision>
 
         <!--spting/web-->
         <spring.version>5.3.14</spring.version>