add epcis docs

Author: Zvonimir

docs/build-a-dkg-node-ai-agent/plugins/epcis-plugin.md

@@ -7,19 +7,26 @@ It provides both HTTP endpoints and MCP tools for:
 - capturing EPCIS documents
 - checking capture status
 - querying events with filters
-- retrieving published assets by UAL
+- tracking an item journey with full traceability
 
 ## Source
 
 - Plugin code: `packages/plugin-epcis/src/index.ts`
 - Query service: `packages/plugin-epcis/src/services/epcisQueryService.ts`
 - Integration guide: `packages/plugin-epcis/docs/EPCIS-Integration-Guide.md`
 
+## Runtime state in this repository
+
+- The current main server setup in `apps/agent/src/server/index.ts` does **not** register `@dkg/plugin-epcis` by default.
+- This means `/epcis/*` routes and EPCIS MCP tools are unavailable in the default runtime until the plugin is mounted.
+- `epcis.read` and `epcis.write` are still declared OAuth scopes, but they only take effect for EPCIS once the plugin and HTTP scope guards are enabled.
+
 ## Quick Start
 
-1. Ensure publisher plugin and epcis plugin is enabled in server plugin registration:
-   - `apps/agent/src/server/index.ts` should include `dkgPublisherPlugin` in the `plugins` array.
+1. Enable EPCIS + publisher plugins in server plugin registration (this is not enabled by default in this repo):
    - `apps/agent/src/server/index.ts` should include `epcisPlugin` in the `plugins` array.
+   - `apps/agent/src/server/index.ts` should include `dkgPublisherPlugin` in the `plugins` array.
+   - If you want route-level EPCIS scope enforcement, apply `applyEpcisHttpScopeGuards(api, authorized)` in the auth middleware plugin.
 2. Run publisher plugin setup:
    - `cd packages/plugin-dkg-publisher && npm run setup`
    - This initializes publisher configuration (including `.env.publisher`) for the publisher flow.
@@ -56,13 +63,15 @@ Implementation note: EPCIS MCP tool handlers are guarded with `withRequiredMcpSc
 - `GET /epcis/events`  
   Queries EPCIS events with filtering and pagination.
 
-- `GET /epcis/asset/*ual`  
-  Retrieves an EPCIS asset by UAL.
+- `GET /epcis/events/track`  
+  Tracks a single EPC across all event types using full traceability.
 
 ### MCP Tools
 
 - `epcis-query`
 - `epcis-track-item`
+- `epcis-capture`
+- `epcis-capture-status`
 
 ## Configuration
 
@@ -148,6 +157,7 @@ curl "http://localhost:9200/epcis/events?epc=urn:epc:id:sgtin:4012345.011111.100
 - `POST /epcis/capture` validates the EPCIS document structure before publishing.
 - `GET /epcis/capture/:captureID` expects numeric capture IDs from publisher responses.
 - `GET /epcis/events` rejects invalid pagination and empty-string filter parameters.
+- `GET /epcis/events/track` requires a non-empty `epc` query parameter.
 
 ## Troubleshooting
 

docs/getting-started/security.md

@@ -87,10 +87,10 @@ Follow the prompts:
 
 Examples:
 
-- `epcis.read` → EPCIS event read routes only (no MCP)
-- `epcis.write` → EPCIS capture and capture-status routes only (no MCP)
-- `mcp epcis.read` → EPCIS read MCP tools over `/mcp`
-- `mcp epcis.write` → EPCIS capture/capture-status MCP tools over `/mcp`
+- `epcis.read` → EPCIS read scope (effective when EPCIS plugin is enabled)
+- `epcis.write` → EPCIS write scope (effective when EPCIS plugin is enabled)
+- `mcp epcis.read` → EPCIS read MCP tools over `/mcp` (when EPCIS plugin is enabled)
+- `mcp epcis.write` → EPCIS capture/capture-status MCP tools over `/mcp` (when EPCIS plugin is enabled)
 
 **When to use tokens**
 
@@ -112,14 +112,20 @@ DKG Node OAuth Tokens are standard **Bearer tokens**. Include them in the `Autho
 
 Access in the DKG Node is **scope-based**:
 
-- By default:
+- By default in the current `apps/agent/src/server/index.ts` runtime:
   - `/mcp` → requires `mcp` scope
   - `/llm` → requires `llm` scope
   - `/blob` → requires `blob` scope
-  - `GET /epcis/events`, `GET /epcis/events/track` → require `epcis.read`
-  - `POST /epcis/capture`, `GET /epcis/capture/:captureID` → require `epcis.write`
+  - `/change-password` and `/profile` → require authentication (empty scope list)
 - Only users or tokens with those scopes can access the corresponding routes.
 
+EPCIS scopes (`epcis.read`, `epcis.write`) are included in OAuth configuration, but EPCIS routes/tools are available only after the EPCIS plugin is mounted.
+
+When EPCIS is enabled and HTTP guards are applied, this mapping is used:
+
+- `GET /epcis/events`, `GET /epcis/events/track` → `epcis.read`
+- `POST /epcis/capture`, `GET /epcis/capture/:captureID` → `epcis.write`
+
 For EPCIS MCP tools (transported through `/mcp`), `/mcp` still requires `mcp`, and tools additionally require:
 
 - `epcis-query`, `epcis-track-item` → `epcis.read`

packages/plugin-epcis/docs/EPCIS-Integration-Guide.md

@@ -34,6 +34,11 @@ This integration bridges **GS1 EPCIS 2.0** (Electronic Product Code Information
 - **Publish** them as tamper-proof Knowledge Assets on the DKG
 - **Query** events using semantic filters across the distributed network
 
+### Runtime status in this repository
+
+The current default server setup in `apps/agent/src/server/index.ts` does **not** register `@dkg/plugin-epcis` by default.  
+This guide documents EPCIS behavior **when the EPCIS plugin is mounted** (and, for HTTP scope enforcement, when EPCIS scope guards are applied).
+
 ### Why Use DKG for EPCIS?
 
 | Traditional EPCIS       | EPCIS + DKG                           |
@@ -558,6 +563,9 @@ urn:epc:id:gdti:{CompanyPrefix}.{DocumentType}.{SerialNumber}
 
 ## 10. API Reference
 
+> The HTTP routes below are available when `@dkg/plugin-epcis` is registered on the server.
+> In this repository's current default runtime, EPCIS routes are not mounted until you enable the plugin.
+
 ### Authorization and required scopes
 
 All EPCIS HTTP routes require a Bearer token in the `Authorization` header: