feat: enhance documentation on import rules and testing practices for Business Services

Author: bot

docs/agents-template.md

@@ -53,6 +53,21 @@ Update this list for the local project:
 - `tests/`: local test suite.
 - `data/` or `samples/`: example payloads.
 
+## settings.py Import Rules
+
+- Treat the directory containing `settings.py` as the project import root for
+  migration.
+- Import production graph, message, and component modules from paths reachable
+  relative to `settings.py`.
+- If `production.py` is next to `settings.py`, use
+  `from production import prod`.
+- If the application is packaged under a directory next to `settings.py`, use
+  package imports such as `from myapp.production import prod`.
+- Do not ask users to set `PYTHONPATH` to make migration imports work.
+- Do not patch `os.environ["PYTHONPATH"]` or global `sys.path` in application
+  code to hide import problems.
+- Fix import errors by changing the project layout or import statements.
+
 ## IoP Rules
 
 - Prefer a Python `Production` object exported through `PRODUCTIONS`.
@@ -115,6 +130,10 @@ iop --migrate settings.py --dry-run
 iop --migrate settings.py
 ```
 
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
+
 If this repository uses Docker or Compose, add the exact command here:
 
 ```bash

docs/ai-coding.md

@@ -10,7 +10,7 @@ Ask the tool to read the project guidance before it writes code:
 ```text
 You are helping me build an IoP application.
 Read these files first:
-- AGENTS.md
+- local AGENTS.md, if this application repository has one
 - docs/ai-coding.md
 - docs/cookbooks/index.md
 - docs/getting-started/first-steps.md
@@ -19,15 +19,16 @@ Read these files first:
 
 Use the Python Production graph workflow for new applications.
 Do not put component startup logic in __init__(); use on_init().
+Treat the directory containing settings.py as the project import root.
+Import production modules relative to settings.py; do not modify PYTHONPATH.
+Do not use iop --test to test Business Services; use the runtime director.
 Use the relevant cookbook for the task.
 Show the migration and verification commands.
 ```
 
-On the published docs site, open
-[AGENTS.md](https://github.com/grongierisc/interoperability-embedded-python/blob/master/AGENTS.md)
-from the repository root.
-
-For your own IoP application repository, copy the
+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
 [Healthcare AI-assisted coding](healthcare-ai-coding.md).

docs/command-line.md

@@ -377,7 +377,12 @@ python3 -m pip install "iris-persistence>=0.1.0"
 
 ## test
 
-The test command allows testing IoP components. You can optionally specify a test name, classname, and body.
+The test command is a low-level helper for testing IoP components. You can
+optionally specify a test name, classname, and body.
+
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
 
 Basic test:
 ```bash

docs/cookbooks/add-polling-service.md

@@ -31,6 +31,8 @@ Implementation requirements:
 - Do not put startup code in __init__(); use on_init() only if required.
 - Update settings.py to add the service and connect service.Output to the
   destination component.
+- Do not use iop --test to test the service; use the runtime director or
+  production runtime API for service tests.
 - Include migration dry-run and verification commands.
 ```
 
@@ -68,12 +70,12 @@ iop --migrate settings.py
 - Dry-run migration shows the service, target setting, and destination
   component.
 - Unit tests cover any pure Python polling decisions or message construction.
-- Runtime verification confirms `on_poll()` emits the expected message.
+- Runtime verification confirms `on_poll()` emits the expected message through
+  the deployed production context.
 
 ## Common Mistakes
 
 - Polling healthcare HL7v2 files in Python instead of using native HL7 file
   services.
 - Forgetting to connect `service.Output` to the destination.
 - Putting long-lived connection setup in `__init__()` instead of `on_init()`.
-

docs/cookbooks/code-index.md

@@ -70,6 +70,23 @@ When starting from source code, build applications through public imports from
 `iop` and a `Production` graph. Do not copy internal runtime classes such as
 `_BusinessHost` into application code; use them only to understand behavior.
 
+## settings.py Import Quick Reference
+
+Treat the directory containing `settings.py` as the project import root for
+migration. Import the production graph, messages, and components from modules
+reachable relative to that file, such as `from production import prod` or
+`from myapp.production import prod`.
+
+Do not set `PYTHONPATH`, patch `os.environ["PYTHONPATH"]`, or mutate global
+`sys.path` in application code to make migration imports pass. Fix the package
+layout or import statements instead.
+
+## Runtime Test Quick Reference
+
+Do not use `iop --test` as the normal way to test Business Services. Test
+services through the runtime director or production runtime API so the deployed
+production context, component settings, and configured targets are used.
+
 ## Healthcare Add-on
 
 If the code or task mentions HL7v2, FHIR, Health Connect, FHIR bundles, MLLP,

docs/cookbooks/hello-world-production.md

@@ -28,6 +28,8 @@ Requirements:
   the operation.
 - Export PRODUCTIONS = [prod].
 - Do not use __init__() for component startup.
+- Do not use iop --test to test HelloService; use the runtime director or
+  production runtime API for service tests.
 - Show the migration dry-run command and the command to run the production
   migration.
 ```
@@ -99,4 +101,3 @@ iop --migrate settings.py
   `Production` graph.
 - Calling `HelloOperation` directly from `HelloService` instead of sending a
   message through the production target.
-

docs/cookbooks/index.md

@@ -7,9 +7,13 @@ Before using a cookbook, give the assistant this context:
 
 ```text
 You are helping me build an IoP application.
-Read AGENTS.md, settings.py, and the relevant cookbook before changing code.
+Read local AGENTS.md if this application has one, settings.py, and the
+relevant cookbook before changing code.
 Use the Python Production graph workflow for new applications.
 Do not put component startup logic in __init__(); use on_init().
+Treat the directory containing settings.py as the project import root.
+Import production modules relative to settings.py; do not modify PYTHONPATH.
+Do not use iop --test to test Business Services; use the runtime director.
 Show the migration and verification commands.
 ```
 

docs/getting-started/first-steps.md

@@ -151,4 +151,9 @@ iop --migrate settings.py
 
 This command creates the IRIS proxy classes for the Python components and registers `HelloWorld.Production`.
 
+When you need to test `HelloService` at runtime, do not use `iop --test`.
+Business Service tests should go through the runtime director or production
+runtime API so the deployed production context, component settings, and
+configured targets are used.
+
 More information about registering components can be found [here](register-component.md).

docs/getting-started/register-component.md

@@ -58,6 +58,11 @@ Migration registers the generated IRIS proxy classes for `FileService` and
 class. `prod.connect(file.Output, orders)` sets that setting to the destination
 component and records the production graph edge.
 
+When you need to test `FileService` at runtime, do not use `iop --test`.
+Business Service tests should go through the runtime director or production
+runtime API so the deployed production context, component settings, and
+configured targets are used.
+
 ## Settings File Sections
 
 A migration file can define these sections:

docs/production-graph.md

@@ -79,7 +79,8 @@ object graph. It does not silently fall back to IRIS export. Existing deployed
 productions should be reconstructed explicitly with `Production.from_iris(...)`
 before testing by target setting path. Runtime status checks fail closed when the
 current production cannot be verified. `prod.test(...)` remains a compatibility
-alias.
+alias. For Business Services, use this production/director runtime path instead
+of `iop --test`.
 
 `ComponentRef` exposes convenience methods that delegate to its owning
 production: `inspect()`, `start()`, `stop()`, `restart()`, and `test(...)`.