a2a-rails 0.1.0 → 0.2.0

data/README.md

@@ -1,53 +1,37 @@
 # a2a-rails
+<img src="docs/assets/a2a-rails-handwritten-note.png">
+<br/>
+<img src="docs/assets/a2a-railsで広がるAI協働図鑑.png">
 
-Rails-native integration for exposing Rails applications as A2A agents.
+Rails-native integration for exposing Rails applications as A2A v1.0 agents.
 
-> **Status: the v0.1.0 release candidate is prepared and CI-verified; the actual public release is next.**
+> **Release status (2026-10-08):** RubyGems has published **`0.1.0`** and the **`0.2.0.rc2` pre-release**. The current source is being verified as an **unpublished `0.2.0` stable candidate** (Step 26-4). In particular, the Rails/Zeitwerk and migration-generator fixes after rc2 are only in the newer source-built candidate. **No stable `0.2.0` tag, GitHub Release, or RubyGems publication has been authorized.**
 
-## Current Status
+- RubyGems: https://rubygems.org/gems/a2a-rails
+- Published pre-release: https://github.com/cuichangquan/a2a-rails/releases/tag/v0.2.0-rc.2 (stable `0.2.0` not yet released)
+- Previous stable release: https://github.com/cuichangquan/a2a-rails/releases/tag/v0.1.0
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Release record: [docs/release/v0.1.0-record.md](docs/release/v0.1.0-record.md)
+- **Release readiness:** [current release/deployment checklist](docs/release/security-hardening-release-checklist.md) · [v0.1.0 → proposed v0.2 upgrade guide](docs/release/upgrading-v0.1.0-to-v0.2.md). The old rc1 record is historical evidence only.
+- **Roadmap / 次にやること:** [ROADMAP.md](ROADMAP.md) — [Step 26 / Issue #62](https://github.com/cuichangquan/a2a-rails/issues/62) tracks the `0.2.0` stable candidate and release gates; [production Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11) remains open. See [stable-readiness record](docs/release/v0.2.0-stable-readiness.md).
+- **Official A2A TCK results:** [Pinned JSON-RPC MUST report and reproduction](docs/testing/official-a2a-tck.md) — after Step 17-4: **63 passed / 1 failed / 171 skipped / 30 deselected** (pytest). The remaining `CORE-SEND-003` mismatch is tracked [upstream in #202](https://github.com/a2aproject/a2a-tck/issues/202). The TCK workflow is informational, **not** an A2A conformance certificate.
 
-The A2A v1.0 SDK integration path, Gem core, Protocol Adapter, Agent / Skill DSL, Task lifecycle, Configuration, Agent Card generation, Rails Engine HTTP endpoints, generators, source-tree Quick Start, packaged-gem installation path, and v0.1.0 release-candidate metadata are now verified.
+- [A2Aの全体像（日本語・A4 1枚PDF）](docs/guides/a2a-protocol-overview-ja.pdf) — 登場人物・依頼の流れ・主要用語・MCPとの違いをまとめた学習資料。
+- [A2A at a glance (English, A4 one-page PDF)](docs/guides/a2a-protocol-overview-en.pdf) — Roles, workflow, key terms, and how MCP fits.
 
-**Current stage:** Step 15-13 completed — v0.1.0 release-candidate preparation
+## Runnable Rails Demo / 実際に動くサンプル ⭐
 
-**Next step:** **Step 15-14 — Execute the v0.1.0 release: final artifact verification from the exact main commit, public-release readiness, `v0.1.0` tag, RubyGems publication, GitHub Release, and post-release smoke verification.**
+**[a2a-rails-demo — independent Rails 8 Echo Agent](https://github.com/cuichangquan/a2a-rails-demo)**
 
-Step 15-13 adds `CHANGELOG.md`, canonical v0.1.0 release notes, a pre-release / publish / post-release checklist, and final RubyGems metadata for source, changelog, documentation, issue tracker, and MFA. The packaged-gem smoke now verifies those metadata fields plus README, CHANGELOG, LICENSE, Ruby compatibility, generator discovery, clean-app installation, Agent Card retrieval, and Echo `SendMessage`. The release-candidate CI is **13 / 13 green**, while the Gem suite remains **70 tests / 240 assertions / 0 failures / 0 errors / 0 skips**. See [Draft PR #7](https://github.com/cuichangquan/a2a-rails/pull/7).
+Run a complete standalone Rails Agent with the current unreleased `a2a-rails` source pinned by Git commit (the published RubyGems v0.1.0 does not contain direct-Message support). The separate Demo covers Agent Card discovery, JSON-RPC v1.0 SendMessage **Task and direct Message**, GetTask, ListTasks and error handling.
 
-Step 15-12 verified the actual built gem in a clean Rails application. Step 15-11 added the intentionally small `install` / `agent` generators and the generator-backed source-tree Quick Start. Step 15-10 implemented the automatically mounted Rails Engine, thin API controllers, a process-local Runtime that shares the in-memory Task Store across HTTP requests, and the Rails-facing SDK logging boundary. Step 15-9 implemented lazy Configuration and Agent Card generation. Step 15-8 wired `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask` through the real SDK. Step 15-7 implemented the SDK-independent Task core. Step 15-6 implemented the Rails-facing Agent / Skill / Dispatcher API. Step 15-5 introduced the loadable Gem skeleton and Protocol Adapter. Step 15-4 verified the `agent2agent 2.0.0` SDK path across the supported Ruby / Rails matrix.
+- [Demo Quick Start, code and example curl requests](https://github.com/cuichangquan/a2a-rails-demo#quick-start).
+- [Demo GitHub Actions smoke](https://github.com/cuichangquan/a2a-rails-demo/actions/workflows/smoke.yml) — independent real HTTP tests **16/16 checks passed** ([PR #1](https://github.com/cuichangquan/a2a-rails-demo/pull/1)).
+- **Local-only development/test** demo: no trusted verifier or durable Task store, **not** an internet-facing production template. See [production security](docs/guides/production-security.md).
 
-## Development Progress
+## What is a2a-rails?
 
-- [x] 1. Research A2A Protocol v1.0
-- [x] 2. Research Ruby A2A SDKs / Gems
-- [x] 3. Research Rails-oriented A2A alternatives
-- [x] 4. Define the problem a2a-rails solves
-- [x] 5. Define v0.1 scope
-- [x] 6. Define terminology
-- [x] 7. Define architecture
-- [x] 8. Define Ruby SDK boundary
-- [x] 9. Public API Design
-- [x] 10. Agent Card Design
-- [x] 11. Task Lifecycle Design
-- [x] 12. Test Strategy
-- [x] 13. Gem Structure
-- [x] 14. Quick Start Design
-- [ ] **15. Implementation / release preparation ← IN PROGRESS**
-  - [x] 15-4 SDK compatibility spike
-  - [x] 15-5 Gem skeleton + Protocol Adapter
-  - [x] 15-6 Agent / Skill DSL + Dispatcher
-  - [x] 15-7 Task core + MemoryStore
-  - [x] 15-8 Task operations through real SDK
-  - [x] 15-9 Configuration + Agent Card
-  - [x] 15-10 Rails Engine HTTP integration
-  - [x] 15-11 Generators + generated Quick Start
-  - [x] 15-12 Packaged-gem / release-readiness verification
-  - [x] 15-13 v0.1.0 release-candidate preparation
-  - [ ] 15-14 v0.1.0 release execution
-
-## v0.1 Direction
-
-v0.1 is **server-first** and focuses on exposing a Rails application as an A2A Agent.
+`a2a-rails` lets a Rails application expose an A2A-compatible Agent without making application code depend directly on SDK-specific request and response objects.
 
 ```text
 A2A Protocol
@@ -61,61 +45,76 @@ Rails Application
 Business Logic
 ```
 
-Main principles:
+The Gem provides:
 
-- Do not reimplement the A2A Protocol.
-- Focus on Rails integration.
-- Keep SDK-specific APIs out of the public API.
-- Prefer a small, non-streaming server scope for v0.1.
-- Keep a2a-rails independent from ActingFor.
+- a Rails-native Agent / Skill DSL;
+- A2A Agent Card generation;
+- automatically mounted A2A HTTP endpoints;
+- synchronous Task execution by default, plus opt-in ActiveJob-backed async Task execution on unreleased `main`;
+- SDK-independent Handler inputs;
+- a process-local MemoryStore by default, plus an optional durable ActiveRecordStore on unreleased main;
+- Rails generators for initial setup;
+- an internal Protocol Adapter boundary around the upstream SDK.
 
-## Quick Start
+v0.1 is intentionally **server-first** and **non-streaming**.
 
-> The flow below is runtime-verified both from the repository source tree and from the built `a2a-rails-0.1.0` gem installed into a clean Rails application.
+> [!WARNING]
+> **Security / production use:** v0.1.0 does not provide built-in authentication or per-caller Task authorization. Do not expose `POST /a2a` to untrusted clients. Before public deployment, protect the endpoint at your application's or network's security boundary. Security hardening is tracked in [Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11).
+
+## Requirements
+
+- Ruby `>= 3.3`
+- Rails `>= 8.0, < 8.2`
+- A2A protocol version `1.0`
+- `agent2agent ~> 2.0.0`
 
-### 1. Add and install
+The original v0.1.0 baseline was verified against:
+
+- Ruby 3.3 / 3.4 / 4.0
+- Rails 8.0 / 8.1
+
+## Installation
+
+Add the Gem to an existing Rails application:
 
 ```bash
 bundle add a2a-rails
+```
+
+Then generate the initializer and an Agent scaffold:
+
+```bash
 bin/rails generate a2a:rails:install
 bin/rails generate a2a:rails:agent echo
-mkdir -p app/services/echo
 ```
 
-`install` creates only:
+No explicit Engine mount or host `config/routes.rb` change is required.
 
-```text
-config/initializers/a2a_rails.rb
-```
+## Quick Start
 
-with:
+The following Echo flow is verified against the published `a2a-rails 0.1.0` Gem in a clean Rails 8.1 application.
 
-```ruby
-A2A::Rails.configure do |config|
-  config.agent = "YourAgent"
-  config.public_base_url = ENV["A2A_PUBLIC_BASE_URL"]
-end
+### 1. Generate the setup
+
+```bash
+bin/rails generate a2a:rails:install
+bin/rails generate a2a:rails:agent echo
+mkdir -p app/services/echo
 ```
 
-`agent echo` creates only:
+The install generator creates:
 
 ```text
-app/agents/echo_agent.rb
+config/initializers/a2a_rails.rb
 ```
 
-with:
-
-```ruby
-class EchoAgent < A2A::Rails::Agent
-  name "Echo Agent"
-  description "TODO"
-  version "1.0"
+The Agent generator creates:
 
-  # Add at least one skill.
-end
+```text
+app/agents/echo_agent.rb
 ```
 
-The generator deliberately does **not** create a Handler, route, controller, Task Store, job, migration, or registration side effect. It also does not reference a Handler that does not exist yet.
+The generators deliberately do not create application business logic, jobs, migrations, Task Stores, or routing side effects.
 
 ### 2. Create the Handler
 
@@ -133,7 +132,9 @@ class Echo::Reply
 end
 ```
 
-### 3. Define the Skill
+Handlers receive SDK-independent Ruby Hashes for `message` and `context`.
+
+### 3. Define the Agent and Skill
 
 Replace `app/agents/echo_agent.rb` with:
 
@@ -163,16 +164,20 @@ A2A::Rails.configure do |config|
 end
 ```
 
-For localhost, leave `A2A_PUBLIC_BASE_URL` unset or set it to `http://localhost:3000`. The Agent class name remains a String until an A2A endpoint resolves it, preserving Rails autoload / reload behavior.
+For localhost, leave `A2A_PUBLIC_BASE_URL` unset or set it to `http://localhost:3000`.
 
-No explicit Engine mount or host `config/routes.rb` change is required.
+The Agent class name remains a String until an A2A endpoint resolves it, preserving Rails autoload / reload behavior.
 
 ### 5. Check the Agent Card
 
+Start Rails:
+
 ```bash
 bin/rails server
 ```
 
+Then request the Agent Card:
+
 ```bash
 curl -sS http://localhost:3000/.well-known/agent-card.json \
   -H "A2A-Version: 1.0"
@@ -183,9 +188,9 @@ Expected essentials:
 - HTTP 200
 - Agent name `Echo Agent`
 - Skill ID `reply`
-- JSON-RPC A2A interface pointing to `http://localhost:3000/a2a`
+- A2A interface URL ending in `/a2a`
 
-### 6. Send the first message
+### 6. Send a message
 
 ```bash
 curl -sS -X POST http://localhost:3000/a2a \
@@ -205,16 +210,18 @@ curl -sS -X POST http://localhost:3000/a2a \
   }'
 ```
 
-Success means:
+A successful response reaches:
 
 ```text
 result.task.status.state == TASK_STATE_COMPLETED
 Artifact Text Part == "Echo: Hello"
 ```
 
-See [the complete Quick Start design and verification notes](docs/design/quick-start.md).
+See [docs/design/quick-start.md](docs/design/quick-start.md) for the design and verification notes behind this flow.
+
+## Public Rails API
 
-## Target Developer Experience
+A minimal Agent looks like this:
 
 ```ruby
 class ShoppingAgent < A2A::Rails::Agent
@@ -248,11 +255,11 @@ A2A::Rails.configure do |config|
 end
 ```
 
-v0.1 targets **one public A2A Agent per Rails application**. Handlers receive SDK-independent Ruby Hashes for `message` and `context`.
+v0.1 targets **one public A2A Agent per Rails application**.
 
-For multiple Skills, the application supplies a Router. The Router receives `skills:` as a frozen `Array<Symbol>` of declared Skill IDs and may return a matching Symbol or String. Unknown selections raise `A2A::Rails::UnknownSkillError`; the Dispatcher never silently chooses the first Skill.
+For multiple Skills, the application supplies a Router. The Router receives `skills:` as a frozen `Array<Symbol>` of declared Skill IDs and may return a matching Symbol or String. Unknown selections raise `A2A::Rails::UnknownSkillError`; the Dispatcher does not silently choose the first Skill.
 
-## Agent Card
+## HTTP Endpoints
 
 The Gem automatically exposes:
 
@@ -261,20 +268,47 @@ GET  /.well-known/agent-card.json
 POST /a2a
 ```
 
-Agent Card behavior:
+The Rails Engine is mounted automatically.
+
+### Security work on main (unreleased; not in published v0.1.0)
+
+The unreleased `main` branch includes a host-provided `config.authenticate_request` callback for `POST /a2a`, plus per-principal Task ownership checks. Without an authenticator, production and other non-development/test environments fail closed; the local development/test Quick Start remains available. See [Authentication guide](docs/guides/authentication.md).
+
+> **Important:** These protections are **absent from RubyGems 0.1.0** but included in the published `0.2.0.rc2` pre-release; the stable candidate has additional fixes. Neither pre-release nor stable source automatically makes a deployed endpoint production-secure. Distributed rate limits, business authorization and the deployment review remain tracked in [Issue #11](https://github.com/cuichangquan/a2a-rails/issues/11).
+
+### Step 16-4 request hardening (merged on main; unreleased)
+
+The unreleased main branch adds a bounded JSON-RPC body (`config.max_request_bytes`, default 1 MiB), Content-Type validation, stricter parameter checks, a pagination snapshot cap, and reduced exception logging. See [Request Hardening Guide](docs/guides/request-hardening.md).
+
+Rate limiting, application-specific authorization and production deployment safeguards remain the host's responsibility or future work. Step 16-5 adds explicit A2A Agent Card Bearer authentication advertisement on unreleased `main`; it must match the host verifier. **These improvements are not included in the published v0.1.0 Gem; see the later rc2 pre-release and current stable candidate.**
+
+### Production deployment review (Step 16-6)
+
+**Current verdict: NO-GO by default for open public production.** The default MemoryStore remains process-local. Step 21 provides an optional durable ActiveRecordStore, and Step 22 provides optional ActiveJob Task execution, but production async operation requires **both** a shared/durable Task Store and a durable queue backend operated by the host. A real deployment must also provide credential verification, business authorization, TLS/proxy restrictions, distributed rate limits, execution budgets, observability and deployment-specific verification.
 
-- generated from the Agent / Skill DSL;
-- Skill IDs and default display names are generated from Skill declarations;
+- [Production security & deployment guide](docs/guides/production-security.md) — responsibilities, sample configuration, security checks and current blockers.
+- [Security release checklist](docs/release/security-hardening-release-checklist.md) — release/upgrade decision, acceptance criteria and artifact verification.
+
+Do **not** interpret successful source-tree CI or a merge to `main` as publication of a new RubyGems release.
+
+
+## Agent Card
+
+Agent Cards are generated from the Agent / Skill DSL.
+
+Behavior in v0.1:
+
+- Skill IDs and default display names come from Skill declarations;
 - optional `examples`, `input_modes`, and `output_modes` map to A2A Agent Card fields;
-- Handler internals are never exposed;
+- Handler internals are not exposed;
 - `public_base_url` wins when configured, otherwise the request base URL is used;
 - default input/output mode is `text/plain`;
-- Streaming, Push Notifications, and Extended Agent Cards are disabled for v0.1;
-- generated Cards pass the real `agent2agent 2.0.0` Agent Card schema.
+- Streaming, Push Notifications, and Extended Agent Cards are disabled;
+- generated Cards pass the `agent2agent 2.0.0` Agent Card schema.
 
 ## Task Lifecycle
 
-Internally the Gem keeps SDK-independent Task states:
+Internally, `a2a-rails` keeps SDK-independent Task states:
 
 ```text
 SUBMITTED
@@ -302,114 +336,65 @@ String       → Text Part
 Hash / Array → Data Part
 nil          → no Artifact
 other object → ArtifactMappingError
-```
-
-v0.1 Task behavior:
-
-- server-generated Task IDs;
-- client Context ID preserved, otherwise server-generated;
-- terminal states are immutable;
-- thread-safe process-local `Task::MemoryStore` by default;
-- `SendMessage`, `GetTask`, `ListTasks`, and `CancelTask` supported;
-- `ListTasks` supports context/state/timestamp filters, stable newest-first ordering, page sizes 1–100, and opaque snapshot pagination;
-- cancellation is atomic, but does not interrupt Handler execution or undo business side effects;
-- v0.1 Handler execution accepts text Message Parts;
-- continuing an existing Task via `message.taskId` is not supported;
-- `INPUT_REQUIRED` and `AUTH_REQUIRED` are out of scope.
 
-The default store is for development and simple synchronous workloads. Tasks and pagination cursors are process-local and are not durable across process restarts or shared between processes.
-
-## Rails Integration
-
-Step 15-10 provides:
-
-- an automatically mounted Rails Engine;
-- thin `ActionController::API` controllers;
-- `/.well-known/agent-card.json` and `/a2a` routes;
-- lazy application Agent resolution;
-- one process-local Runtime that shares the default Task Store across HTTP requests;
-- request-derived Agent Card URL fallback;
-- a logging boundary that suppresses the upstream SDK `A2A::Server::Triage` INFO log containing the full Rack environment while restoring prior Console logging state afterward.
-
-## Generators
-
-Step 15-11 implements:
-
-```text
-a2a:rails:install
-a2a:rails:agent NAME
+Unreleased Step 17-3 (not in RubyGems v0.1.0):
+A2A::Rails::FileArtifact.bytes(...) → File Part with base64 raw bytes
+A2A::Rails::FileArtifact.url(...)   → File Part with an HTTPS URL
 ```
 
-Verified contract:
-
-- `install` creates only `config/initializers/a2a_rails.rb`;
-- `agent echo` creates only `app/agents/echo_agent.rb`;
-- the Agent scaffold has no dangling Handler reference;
-- the generated Agent is not automatically registered;
-- namespace-based generator invocation reproduces the documented files;
-- the generated Echo setup boots under Rails and completes a real A2A `SendMessage` request.
-
-Step 15-12 verifies the same generator contract from the **built and installed gem**, in a clean Rails application outside the repository source checkout.
-
-## Packaged Gem Verification
+**File Artifact output is unreleased.** Rails Handlers can explicitly return a `FileArtifact.bytes(data:, filename:, media_type:)` or `FileArtifact.url(url:, filename:, media_type:)`. See the [File Artifact output guide](docs/guides/file-artifacts.md). Input file Parts, downloading remote URLs and production file authorization are not supplied by the Gem.
 
-Step 15-12 verifies the distribution artifact itself:
+**Unreleased Step 17-4:** A2A v1.0 also permits a direct `Message` from `SendMessage`. The host Agent can opt into `response_mode :message` or select the mode using a callable; the default remains `:task`. Direct replies do **not** create Task records. See the [Direct Message response guide](docs/guides/direct-message-responses.md) for the contract and safety implications.
 
-- `gem build a2a-rails.gemspec` produces `a2a-rails-0.1.0`;
-- the package contains the Engine, generator classes, generator templates, and routes required at runtime;
-- the clean app resolves `a2a-rails-0.1.0` from the installed RubyGems path, not from the repository checkout;
-- actual `bin/rails generate` commands discover both generators;
-- generated files match the documented scaffold contract;
-- the clean app boots and serves the generated Agent Card;
-- `SendMessage` completes with the Echo Artifact;
-- Step 15-12 verified package SHA256: `09c55122c5d5e6cb5f9b735664d70b000f67d23dcaad9f4a8ff960dbe02dd410`.
+Supported Task operations:
 
-Step 15-13 extends this verification to user-facing release files and RubyGems metadata. The final published artifact must still be rebuilt and hashed from the exact tagged release commit.
+- `SendMessage`
+- `GetTask`
+- `ListTasks`
+- `CancelTask`
 
-## Release Candidate
+`ListTasks` supports context/state/timestamp filters, stable newest-first ordering, page sizes 1–100, and opaque snapshot pagination.
 
-Step 15-13 prepares, but does not publish, v0.1.0:
+The default `Task::MemoryStore` is thread-safe but process-local. Tasks and pagination cursors are not durable across process restarts and are not shared between processes.
 
-- [CHANGELOG](CHANGELOG.md)
-- [v0.1.0 release notes](docs/release/v0.1.0.md)
-- [v0.1.0 release checklist](docs/release/v0.1.0-checklist.md)
-
-The gemspec publishes canonical links for source code, changelog, documentation, and issue tracking, and requires RubyGems MFA. `README.md`, `CHANGELOG.md`, and `LICENSE` are verified as package contents.
+**Unreleased Step 21:** applications that need durable, multi-worker Task state can opt into `config.task_store = :active_record`. The ActiveRecordStore uses owner-scoped SQL access, row-locked transitions, signed keyset cursors, terminal retention, bounded pruning and maintenance limits. See [ActiveRecord Task Store](docs/guides/active-record-task-store.md). PostgreSQL 16 persistence/locking smoke is verified in CI.
 
-No `v0.1.0` tag, RubyGems publication, GitHub Release, or repository-visibility change is performed in Step 15-13.
+**Unreleased Step 22:** Task execution remains synchronous by default. Hosts can opt into ActiveJob-backed async execution globally, per Agent, or per Skill; precedence is **Skill > Agent > global**.
 
-## Test Strategy
+```ruby
+A2A::Rails.configure do |config|
+  config.task_store = :active_record
+  config.task_execution_mode = :async
+end
 
-v0.1 uses **Minitest** with four layers:
+class ReportsAgent < A2A::Rails::Agent
+  execution_mode :sync
 
-```text
-4. Protocol E2E / Smoke Tests
-3. Rails Integration Tests
-2. Adapter Contract Tests
-1. Core Unit Tests
+  skill :build_report,
+    description: "Build a report",
+    tags: %w[report],
+    handler: Reports::Build,
+    execution_mode: :async
+end
 ```
 
-The current CI matrix covers:
+Async `SendMessage` persists and returns a `SUBMITTED` Task, then a Gem-owned ActiveJob worker claims it atomically and executes the already-selected Skill. Direct-Message responses remain synchronous because they do not create a persisted Task to poll.
 
-- Gem: Ruby 3.3 / 3.4 / 4.0
-- SDK spike: Ruby 3.3 / 3.4 / 4.0
-- Rails: Ruby 3.3 / 3.4 / 4.0 × Rails 8.0 / 8.1
-- Packaged gem: Ruby 3.4 + clean Rails 8.1 application
+Production async use requires a shared/durable Task Store plus a durable ActiveJob backend. The Gem does not provide a distributed transaction between Task persistence and queue enqueue: a small crash window remains after Task commit and before queue acknowledgement. Generic Handler retries are intentionally disabled; duplicate Job delivery is suppressed at Task claim, but exactly-once external side effects are **not** guaranteed. Running cancellation is logical/best-effort, and ambiguous `WORKING` Tasks are not automatically replayed after a worker crash. See [ActiveJob Task Execution](docs/design/active-job-task-execution.md) and [queue adapter / HTTP async verification](docs/testing/queue-adapters.md).
 
-Current Step 15-13 result:
+Cancellation changes Task state atomically, but does not stop already-running Handler code or reverse application side effects.
 
-```text
-13 / 13 CI jobs green
-70 tests
-240 assertions
-0 failures
-0 errors
-0 skips
-```
+## Architecture
 
-Known warning-enabled output from upstream `agent2agent 2.0.0` remains, including circular-require / indentation / URI-parser warnings. Those warnings are distinct from the Rack-environment INFO logging that a2a-rails suppresses at the Rails-facing adapter boundary.
+Key boundaries:
 
-## Gem Structure
+- Rails Engine / controllers / routes form the Rails integration layer;
+- SDK-specific behavior stays behind `Protocol::Adapter` / `Protocol::Agent2AgentAdapter`;
+- A2A camelCase fields, `TASK_STATE_*`, SDK schema objects, and SDK errors stay in the Protocol layer;
+- Agent / Handler application constants are resolved lazily through Rails;
+- ActiveRecord is optional and loaded only when ActiveRecordStore is selected; ActiveJob is not a runtime requirement.
+
+Gem structure:
 
 ```text
 lib/a2a/rails/
@@ -429,23 +414,6 @@ lib/generators/a2a/rails/
 └── templates/
 ```
 
-Key boundaries:
-
-- Rails Engine / controllers / routes are only the Rails integration layer.
-- SDK-specific behavior stays behind `Protocol::Adapter` / `Protocol::Agent2AgentAdapter`.
-- A2A camelCase fields, `TASK_STATE_*`, SDK schema objects, and SDK errors stay in the Protocol layer.
-- Agent / Handler application constants remain lazily resolved through Rails.
-- ActiveRecord and ActiveJob are not runtime requirements.
-- v0.1 targets Ruby `>= 3.3` and Rails `>= 8.0, < 8.2`.
-
-Current main dependencies:
-
-- `agent2agent ~> 2.0.0`
-- `actionpack >= 8.0, < 8.2`
-- `json < 3`
-- `rack >= 3.0, < 4`
-- `railties >= 8.0, < 8.2`
-
 ## v0.1 Scope
 
 Included:
@@ -456,15 +424,14 @@ Included:
 - Agent Card generation
 - `/.well-known/agent-card.json`
 - `POST /a2a`
-- Task lifecycle
-- `GetTask`, `ListTasks`, `CancelTask`
+- synchronous Task lifecycle
+- `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`
 - `A2A-Version: 1.0` validation
 - in-memory Task Store
 - Rails Engine / Routes
 - Configuration
 - `install` / `agent` generators
 - Rails logging boundary
-- test support
 
 Not included in v0.1:
 
@@ -474,26 +441,116 @@ Not included in v0.1:
 - SSE / BiDi Streaming
 - Push Notifications
 - gRPC
-- Human-in-the-loop
-- `INPUT_REQUIRED` / `AUTH_REQUIRED` flows
-- Agent Registry / Marketplace
+- Human-in-the-loop flows
+- `INPUT_REQUIRED` / `AUTH_REQUIRED`
 - OAuth Server
+- Agent Registry / Marketplace
 - Authorization Engine
 - ActingFor integration
 - Admin UI
 - LLM Agent Framework
 - Orchestration Framework
 
+## Verification
+
+The v0.1.0 release candidate completed:
+
+```text
+13 / 13 CI jobs green
+70 tests
+240 assertions
+0 failures
+0 errors
+0 skips
+```
+
+After publication, `a2a-rails 0.1.0` was fetched back from RubyGems and its SHA256 matched the exact artifact that was pushed.
+
+Final published artifact SHA256:
+
+```text
+23d34bde6f436723bf01735f3a507cf8529975b1dfed5d5da9b063fc0480b19f
+```
+
+A fresh Rails 8.1 application then installed the published Gem from RubyGems and verified:
+
+```text
+Agent Card HTTP: 200
+Agent name: Echo Agent
+Skill: reply
+SendMessage HTTP: 200
+Task state: TASK_STATE_COMPLETED
+Artifact: Echo: Hello
+```
+
+See [docs/release/v0.1.0-record.md](docs/release/v0.1.0-record.md) for the complete release evidence.
+
+## Cross-language A2A interoperability — unreleased main source
+
+[Step 18 / PR #27](https://github.com/cuichangquan/a2a-rails/pull/27) verified the **official** Python `a2a-sdk==1.2.2` and Go `a2a-go/v2 v2.6.0` clients against a loopback-only Rails JSON-RPC A2A v1.0 Agent. Both discovered Agent Cards, decoded Task and direct Message responses, queried Tasks and checked terminal cancellation and version errors.
+
+- [Final official Python/Go interoperability CI](https://github.com/cuichangquan/a2a-rails/actions/runs/37576849497) — **both PASS**.
+- [Final Ruby/Rails regression CI](https://github.com/cuichangquan/a2a-rails/actions/runs/37576849516) — **13/13 PASS**.
+- [Interop test code, reproduction and limitations](docs/testing/cross-language-interop.md).
+
+This evidence applies to the later source/pre-release line, not RubyGems v0.1.0; these tests do not certify full A2A interoperability or public-production safety.
+
+## Test Strategy
+
+v0.1 uses Minitest with four layers:
+
+```text
+4. Protocol E2E / Smoke Tests
+3. Rails Integration Tests
+2. Adapter Contract Tests
+1. Core Unit Tests
+```
+
+The CI matrix covers:
+
+- Gem: Ruby 3.3 / 3.4 / 4.0
+- SDK spike: Ruby 3.3 / 3.4 / 4.0
+- Rails: Ruby 3.3 / 3.4 / 4.0 × Rails 8.0 / 8.1
+- Packaged Gem: Ruby 3.4 + clean Rails 8.1 application
+
+Known warning-enabled output from upstream `agent2agent 2.0.0` can include circular-require, indentation, and URI-parser warnings. Those warnings are distinct from the Rack-environment INFO logging that `a2a-rails` suppresses at the Rails-facing adapter boundary.
+
+## Release Documents
+
+- [CHANGELOG](CHANGELOG.md)
+- [v0.1.0 Release Notes](docs/release/v0.1.0.md)
+- [v0.1.0 Release Checklist](docs/release/v0.1.0-checklist.md)
+- [v0.1.0 Release Record](docs/release/v0.1.0-record.md)
+
 ## Design Documents
 
 - [v0.1 Design Decisions](docs/design/v0.1-decisions.md)
 - [v0.1 Test Strategy](docs/design/test-strategy.md)
 - [v0.1 Gem Structure](docs/design/gem-structure.md)
 - [v0.1 Quick Start Design](docs/design/quick-start.md)
-- [Step 15 SDK compatibility findings](docs/design/sdk-compatibility-spike.md)
+- [SDK compatibility findings](docs/design/sdk-compatibility-spike.md)
 
-## Release Documents
+## License
 
-- [CHANGELOG](CHANGELOG.md)
-- [v0.1.0 Release Notes](docs/release/v0.1.0.md)
-- [v0.1.0 Release Checklist](docs/release/v0.1.0-checklist.md)
+The Gem is available as open source under the terms of the MIT License. See [LICENSE](LICENSE).
+
+## Official A2A Resources / A2A公式資料
+
+- [A2A Protocol overview / A2Aの全体像（日本語・A4 1枚PDF）](docs/guides/a2a-protocol-overview-ja.pdf) — 公式資料をもとに作成した学習資料（2026-10-07）。
+- [A2A at a glance (English, A4 one-page PDF)](docs/guides/a2a-protocol-overview-en.pdf) — Learning guide based on the official documentation (2026-10-07).
+- [A2A Protocol documentation (Latest) / 公式ドキュメント](https://a2a-protocol.org/latest/)
+- [A2A Protocol v1.0.0 documentation / v1.0.0ドキュメント](https://a2a-protocol.org/v1.0.0/)
+- [A2A v1.0.0 Specification / v1.0.0仕様書](https://a2a-protocol.org/v1.0.0/specification/)
+- [Official GitHub / 公式GitHub: a2aproject/A2A](https://github.com/a2aproject/A2A)
+- [Official samples / 公式サンプル: a2aproject/a2a-samples](https://github.com/a2aproject/a2a-samples)
+
+## Articles & Community / 紹介記事・コミュニティ
+
+### Japanese articles / 日本語の紹介記事
+
+- [Zenn: RailsアプリをA2A対応Agentとして公開する「a2a-rails」を作りました](https://zenn.dev/ccq/articles/d52c1b29982663)
+- [Qiita: RailsアプリをA2A対応Agentとして公開する「a2a-rails」を作りました](https://qiita.com/ccq1170/items/0852445745403c8e848b)
+
+### Community submissions / コミュニティへの投稿
+
+- [awesome-a2a: Resource suggestion #190 / 掲載提案](https://github.com/ai-boost/awesome-a2a/issues/190)

data/app/controllers/a2a/rails/agent_cards_controller.rb

@@ -5,7 +5,10 @@ module A2A
     class AgentCardsController < ApplicationController
       def show
         response.set_header("A2A-Version", Protocol::Agent2AgentAdapter::PROTOCOL_VERSION)
+        response.set_header("Cache-Control", "no-store")
         render json: A2A::Rails.runtime.agent_card(request_base_url: request.base_url)
+      rescue A2A::Rails::ConfigurationError
+        render json: { error: "Agent Card unavailable" }, status: :service_unavailable
       end
     end
   end