Add IoP cookbooks and agent guidance installation

- Introduced new cookbooks for building IoP applications, including general workflows, healthcare workflows, and production settings.
- Added a comprehensive guide for registering components in IoP applications.
- Created a guide for healthcare AI-assisted coding, emphasizing the use of native IRIS components.
- Implemented a production change workflow to manage changes in existing IRIS productions.
- Added a validation skill for IoP applications, including unit tests and migration checks.
- Enhanced CLI with an option to install agent guidance, allowing users to set up IoP guides and skills easily.
- Developed unit tests for the new agent guidance functionality and ensured proper package data declarations.

Author: grongierisc

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Add `iop --install-agent-guidance` to install version-matched IoP guidance,
+  skills, and offline cookbooks into existing application repositories for
+  Codex, Claude Code, and Gemini CLI.
+- Add portable `build-iop-app` and `validate-iop-app` Agent Skills that can also
+  be installed directly from the framework repository.
+- Preserve existing project instructions through idempotent managed blocks,
+  with agent selection, conflict preflight, and explicit forced refresh support.
+
+### Changed
+- Make the packaged Agent Skill references the source of truth for IoP
+  cookbooks and related AI guidance; MkDocs pages include them using the same
+  snippet pattern as the changelog.
+
 ## [4.1.0] - 2026-07-16
 ### Changed
 - Move remote debugging support to the optional `debug` extra. Install

MANIFEST.in

@@ -3,3 +3,4 @@ include LICENSE
 include AGENTS.md
 include mkdocs.yml
 recursive-include docs *.md
+recursive-include src/iop/ai *.md

README.md

@@ -11,7 +11,15 @@ Welcome to **Interoperability On Python (IoP)**, a production-stable Python-firs
 Documentation can be found [here](https://grongierisc.github.io/interoperability-embedded-python/).
 For prompt-driven workflows, see [AI-assisted coding with IoP](https://grongierisc.github.io/interoperability-embedded-python/ai-coding/).
 For task-oriented examples, see the [IoP cookbooks](https://grongierisc.github.io/interoperability-embedded-python/cookbooks/).
-For application repositories, start from the [reusable AGENTS.md template](https://grongierisc.github.io/interoperability-embedded-python/agents-template/).
+For any application repository, install version-matched agent guidance, skills,
+and offline cookbooks with:
+
+```bash
+iop --install-agent-guidance
+```
+
+See [IoP Agent Guidance And Skills](https://grongierisc.github.io/interoperability-embedded-python/agent-guidance/)
+for Codex, Claude Code, Gemini CLI, and direct Agent Skills installation.
 
 ## Example
 

docs/agent-guidance.md

@@ -0,0 +1 @@
+--8<-- "src/iop/ai/skills/build-iop-app/references/agent-guidance.md"

docs/agents-template.md

@@ -1,8 +1,10 @@
 # Reusable AGENTS.md For IoP Projects
 
-Copy this template into the root of an application repository as `AGENTS.md`.
-Keep it generic. Put project-specific details in the project README or in a
-short project brief section.
+Prefer `iop --install-agent-guidance` to configure Codex, Claude Code, Gemini
+CLI, portable skills, and offline cookbooks together. Copy this fallback
+template into an application repository as `AGENTS.md` only when the installer
+cannot be used. Keep it generic and put project-specific details in the project
+README or a short project brief section.
 
 ````md
 # Agent Guide

docs/ai-coding.md

@@ -3,6 +3,19 @@
 Use this guide when you want to vibe code with IoP while still getting
 production-shaped, reviewable Python interoperability code.
 
+## Install Project Guidance
+
+IoP can install version-matched guidance, Agent Skills, and offline cookbooks in
+any application repository, whether or not it uses the IoP template:
+
+```bash
+iop --install-agent-guidance
+```
+
+This configures Codex, Claude Code, and Gemini CLI by default. See
+[IoP Agent Guidance And Skills](agent-guidance.md) for agent selection, updates,
+conflict handling, and direct installation from GitHub.
+
 ## Start Here
 
 Ask the tool to read the project guidance before it writes code:
@@ -29,9 +42,9 @@ Show the migration and verification commands.
 
 The IoP framework repository root `AGENTS.md` is for framework source
 development, not application guidance. For your own IoP application repository,
-copy the
-[reusable AGENTS.md template](agents-template.md) into the project root and
-adapt it to the local production. For healthcare projects, also read
+prefer `iop --install-agent-guidance`; the
+[reusable AGENTS.md template](agents-template.md) remains available for manual
+setup. For healthcare projects, also read
 [Healthcare AI-assisted coding](healthcare-ai-coding.md).
 
 ## Cookbooks

docs/command-line.md

@@ -71,6 +71,34 @@ The CLI uses these terms consistently:
 - `unbind` or `unregister`: remove an IOP-generated IRIS proxy class binding.
   This does not delete Python source files or production items.
 
+## install agent guidance
+
+Install version-matched IoP project guidance, Agent Skills, and offline
+cookbooks without connecting to IRIS:
+
+```bash
+iop --install-agent-guidance
+```
+
+The current directory and all supported agents are the defaults. Select clients
+or another project directory explicitly when needed:
+
+```bash
+iop --install-agent-guidance /path/to/project --agent codex
+iop --install-agent-guidance --agent claude --agent gemini
+```
+
+The command preserves content outside its marked blocks in root instruction
+files. It refuses to replace changed IoP-managed assets unless explicitly
+requested:
+
+```bash
+iop --install-agent-guidance --force-agent-guidance
+```
+
+See [IoP Agent Guidance And Skills](agent-guidance.md) for the installed layout
+and direct skill installation.
+
 ## help
 
 The help command display the help and the default production name.

docs/cookbooks/add-business-operation.md

@@ -1,126 +1 @@
-# Cookbook: Add A BusinessOperation
-
-## When To Use This
-
-Use this cookbook when a production needs an outbound side-effect boundary:
-calling an API, writing a file, submitting FHIR, storing data, or wrapping a
-technical operation behind a production message.
-
-## Files You Will Touch
-
-- the operation module, such as `bo.py` or `operations.py`
-- the message module, such as `msg.py` or `messages.py`
-- `settings.py`
-- the fastest relevant test or sample payload
-
-## Prompt To Give Your Agent
-
-```text
-Add a new IoP BusinessOperation to this project.
-
-Business goal:
-<describe what the operation receives, validates, logs, transforms, or sends>
-
-Implementation requirements:
-- Reuse existing message classes if they already fit.
-- If a new message is needed, define it as a Message dataclass unless there is
-  a specific need for PersistentMessage.
-- Implement a fallback on_message(self, request) for simple operations, or route
-  by message type with typed one-argument methods or the @handler decorator.
-- Return a response message or the original request when that matches the flow.
-- Use self.log_info(), self.log_warning(), or self.log_error() for component
-  logging.
-- Do not add startup work to __init__(); use on_init() only if startup work is
-  required.
-- Update settings.py so the operation is added to the Production graph.
-- Add or update the fastest relevant test.
-- Show the exact verification command.
-```
-
-## Expected Implementation
-
-A simple operation can use `on_message()`:
-
-```python
-from iop import BusinessOperation
-
-from messages import OrderRequest, OrderResponse
-
-
-class OrderOperation(BusinessOperation):
-    def on_message(self, request: OrderRequest) -> OrderResponse:
-        self.log_info(f"Processing order {request.order_id}")
-        return OrderResponse(order_id=request.order_id, status="accepted")
-```
-
-When one operation handles multiple message types, prefer typed one-argument
-methods or the `@handler` decorator:
-
-```python
-from iop import BusinessOperation, handler
-
-from messages import CancelOrder, OrderRequest, OrderResponse
-
-
-class OrderOperation(BusinessOperation):
-    def on_message(self, request):
-        self.log_warning(f"Unhandled message {type(request).__name__}")
-        return request
-
-    def submit_order(self, request: OrderRequest) -> OrderResponse:
-        self.log_info(f"Submitting order {request.order_id}")
-        return OrderResponse(order_id=request.order_id, status="accepted")
-
-    @handler(CancelOrder)
-    def cancel_order(self, request):
-        self.log_info(f"Cancelling order {request.order_id}")
-        return request
-```
-
-IoP dispatches to:
-
-- a method decorated with `@handler(MessageType)` first
-- a typed one-argument method such as `submit_order(self, request: OrderRequest)`
-- `on_message(self, request)` as the fallback
-
-The production graph should register the operation:
-
-```python
-operation = prod.operation("OrderOperation", OrderOperation)
-```
-
-If another component sends to the operation, declare a `target()` setting on the
-sender and connect it:
-
-```python
-process = prod.process("OrderProcess", OrderProcess)
-process.connect(OrderProcess.Orders, operation)
-```
-
-## Migration Command
-
-```bash
-iop --migrate settings.py --dry-run
-iop --migrate settings.py
-```
-
-## Verification
-
-Use the fastest local test first:
-
-```bash
-python -m pytest
-```
-
-If there is no existing test suite, ask the agent to add a small test for the
-pure Python transformation or validation logic.
-
-## Common Mistakes
-
-- Creating an operation but not adding it to `settings.py`.
-- Calling another production component as a normal Python object.
-- Hiding connection names in strings instead of using `target()` and
-  `prod.connect(...)`.
-- Using `PersistentMessage` when a regular `Message` dataclass is enough.
-- Adding multiple handlers for the same message type without making the
-  intended precedence explicit.
+--8<-- "src/iop/ai/skills/build-iop-app/references/cookbooks/add-business-operation.md"

docs/cookbooks/add-business-process.md

@@ -1,115 +1 @@
-# Cookbook: Add A BusinessProcess
-
-## When To Use This
-
-Use this cookbook when a production needs routing, orchestration, decision
-logic, enrichment, or coordination between services and operations.
-
-Business Processes should not own external side effects directly when a
-Business Operation is the better boundary. Keep the process focused on deciding
-what happens next and sending messages to downstream targets.
-
-## Files You Will Touch
-
-- the process module, such as `bp.py` or `processes.py`
-- the message module, such as `msg.py` or `messages.py`
-- operation modules only when downstream behavior is missing
-- `settings.py`
-- tests or sample payloads for routing decisions
-
-## Prompt To Give Your Agent
-
-```text
-Add a new IoP BusinessProcess to this project.
-
-Business goal:
-<describe the routing, orchestration, enrichment, or decision logic>
-
-Implementation requirements:
-- Reuse existing message classes if they already fit.
-- Declare outbound routes with target() attributes on the process class.
-- Route messages with send_request_sync(), send_request_async(), or direct
-  response behavior according to the existing project pattern.
-- Use on_message(self, request) for simple processes, or route by message type
-  with typed one-argument methods or the @handler decorator.
-- Keep external API calls, database writes, file writes, and FHIR submission in
-  BusinessOperation classes.
-- Do not add startup work to __init__(); use on_init() only if startup work is
-  required.
-- Update settings.py so the process is added to the Production graph and its
-  targets are connected.
-- Add or update tests for routing decisions.
-- Show the exact migration and verification commands.
-```
-
-## Expected Implementation
-
-A process declares outbound targets and sends messages to them:
-
-```python
-from iop import BusinessProcess, Message, handler, target
-
-from messages import OrderRequest, OrderResponse, RejectedOrder
-
-
-class OrderProcess(BusinessProcess):
-    Accepted = target()
-    Rejected = target()
-
-    def on_message(self, request):
-        self.log_warning(f"Unhandled message {type(request).__name__}")
-        return request
-
-    def route_order(self, request: OrderRequest):
-        if not request.order_id:
-            return self.send_request_sync(self.Rejected, RejectedOrder(reason="missing id"))
-
-        return self.send_request_sync(self.Accepted, request)
-
-    @handler(RejectedOrder)
-    def route_rejected(self, request):
-        self.log_info(request.reason)
-        return request
-```
-
-IoP dispatches to:
-
-- a method decorated with `@handler(MessageType)` first
-- a typed one-argument method such as `route_order(self, request: OrderRequest)`
-- `on_message(self, request)` as the fallback
-
-Wire the process in `settings.py`:
-
-```python
-process = prod.process("OrderProcess", OrderProcess)
-accepted = prod.operation("AcceptedOperation", AcceptedOperation)
-rejected = prod.operation("RejectedOperation", RejectedOperation)
-
-process.connect(OrderProcess.Accepted, accepted)
-process.connect(OrderProcess.Rejected, rejected)
-```
-
-## Migration Command
-
-```bash
-iop --migrate settings.py --dry-run
-iop --migrate settings.py
-```
-
-## Verification
-
-- Unit-test the routing decision with representative messages.
-- Dry-run migration shows the process and all target settings.
-- The production graph contains every expected process edge.
-- Runtime trace shows messages passing from service to process to operation.
-
-## Common Mistakes
-
-- Putting external API calls or database writes directly in the process.
-- Forgetting `target()` declarations for outbound routes.
-- Returning raw dictionaries instead of message objects when the downstream
-  component expects IoP messages.
-- Adding multiple handlers for the same message type without making the
-  intended precedence explicit.
-- Calling a downstream component directly instead of sending a production
-  message through a target.
+--8<-- "src/iop/ai/skills/build-iop-app/references/cookbooks/add-business-process.md"