docs: restore unrelated AGENTS and workflow comments

Signed-off-by: lucarlig <luca.carlig@ibm.com>

Author: lucarlig

.github/workflows/pytest.yml

@@ -91,6 +91,7 @@ jobs:
       # Rust MCP runtime (tools_rust/mcp_runtime) not needed for main pytest suite
       # (e2e_rust tests are excluded and run in separate workflow)
       # -----------------------------------------------------------
+
       # 3️⃣  Run the tests with coverage (fail under 95 %total  coverage)
       # -----------------------------------------------------------
       - name: 🧪  Run pytest

.secrets.baseline

@@ -3,7 +3,7 @@
     "files": "^.secrets.baseline|package-lock.json|Cargo.lock|scripts/sign_image.sh|scripts/zap|sonar-project.properties|uv.lock|go.sum|mcpgateway/sri_hashes.json|^.secrets.baseline$",
     "lines": null
   },
-  "generated_at": "2026-04-15T08:29:37Z",
+  "generated_at": "2026-04-15T08:45:20Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -200,39 +200,39 @@
         "hashed_secret": "f4793151b0607198d4de9b1ca458d3e25adf1cb7",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 110,
+        "line_number": 112,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "fa9beb99e4029ad5a6615399e7bbae21356086b3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 153,
+        "line_number": 188,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "7b4455a56fbf1d198e45e04c437488514645a82c",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 155,
+        "line_number": 190,
         "type": "Secret Keyword",
         "verified_result": null
       },
       {
         "hashed_secret": "90bd1b48e958257948487b90bee080ba5ed00caa",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 227,
+        "line_number": 262,
         "type": "Hex High Entropy String",
         "verified_result": null
       },
       {
         "hashed_secret": "48ffbad96aa9c2b33f9486f5a3c2108198acb518",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 228,
+        "line_number": 263,
         "type": "Hex High Entropy String",
         "verified_result": null
       }
@@ -690,53 +690,59 @@
     "crates/mcp_runtime/src/lib.rs": [
       {
         "hashed_secret": "9d4e1e23bd5b727046a9e3b4b7db57bd8d6ee684",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 10521,
         "type": "Basic Auth Credentials",
-        "verified_result": null
+        "verified_result": false
       }
     ],
     "crates/mcp_runtime/src/observability.rs": [
       {
         "hashed_secret": "b7dd0ec3dc49487982011219e66db3716b6669c6",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 598,
         "type": "Secret Keyword",
-        "verified_result": null
+        "verified_result": false
       }
     ],
     "crates/mcp_runtime/tests/runtime.rs": [
       {
         "hashed_secret": "5b204323030835cdda5d258742d1452e812988de",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 1643,
         "type": "Secret Keyword",
-        "verified_result": null
+        "verified_result": false
       },
       {
         "hashed_secret": "d6c1622f5e897dac7dcc4fab2cded03cb8240caa",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 5296,
         "type": "Secret Keyword",
-        "verified_result": null
+        "verified_result": false
       }
     ],
     "crates/wrapper/scripts/test-fast-time-wrapper.sh": [
       {
         "hashed_secret": "5546721ffdfc2e5b0e4c0da38f10774f9ad50b09",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 12,
         "type": "Secret Keyword",
-        "verified_result": null
+        "verified_result": false
       }
     ],
     "crates/wrapper/src/config.rs": [
       {
         "hashed_secret": "c8190eb36807e51dd78086805a24539885edda6b",
-        "is_verified": false,
+        "is_secret": false,
+        "is_verified": true,
         "line_number": 9,
         "type": "Secret Keyword",
-        "verified_result": null
+        "verified_result": false
       }
     ],
     "docker-compose-debug.yml": [

AGENTS.md

@@ -48,8 +48,9 @@ llms/                       # End-user LLM guidance (not for code agents)
 ```bash
 cp .env.example .env && make install-dev check-env    # Complete setup
 make venv                          # Create virtual environment with uv
-make install-dev                   # Install with dev dependencies
+make install-dev                   # Install with dev dependencies (includes build-ui)
 make check-env                     # Verify .env against .env.example
+make build-ui                      # Rebuild Admin UI JS bundle (requires npm)
 ```
 
 ### Development
@@ -65,10 +66,11 @@ make serve-ssl                    # HTTPS on :4444 (creates certs if needed)
 make autoflake isort black pre-commit
 
 # Before committing, use ty, mypy and pyrefly to check just the new files, then run:
-make flake8 bandit interrogate pylint verify
+make ruff bandit interrogate pylint verify
 
-# Before committing Rust changes (crates/ or tools_rust/):
-make rust-check                   # Runs fmt-check, clippy -D warnings, and cargo test for all Rust crates
+# Before committing Rust changes (tools_rust/):
+# Run fmt-check, clippy -D warnings, and cargo test for Rust crates
+cd tools_rust/mcp_runtime && cargo fmt --check && cargo clippy -- -D warnings && cargo test
 ```
 
 ## Authentication & RBAC Overview
@@ -135,6 +137,39 @@ ContextForge implements a **two-layer security model**:
 - **Multi-tenancy architecture**: `docs/docs/architecture/multitenancy.md`
 - **OAuth token delegation**: `docs/docs/architecture/oauth-design.md`
 
+## Observability Transaction Behavior
+
+**Issue #3883 - Separate Session Pattern**
+
+Observability write operations use **independent database sessions** that commit immediately (best-effort pattern). This means:
+
+- Observability data persists even when the main request fails
+- Traces may show "in progress" or partial states for failed requests
+- **NOT atomic** with main request transaction (intentional trade-off)
+- Provides visibility into partial failures at the cost of atomicity
+
+### Implementation Details
+
+**Write methods** (use independent sessions):
+- `start_trace()`, `end_trace()`
+- `start_span()`, `end_span()`
+- `add_event()`, `record_token_usage()`, `record_metric()`, `delete_old_traces()`
+
+**Query methods** (use request-scoped sessions):
+- `get_trace()`, `get_traces()`, `get_spans()`, etc.
+- These accept a `db: Session` parameter for RBAC/token scoping
+
+**Context managers** (create single independent session for lifecycle):
+- `trace_span()`, `trace_tool_invocation()`, `trace_a2a_request()`
+
+**Pattern**: Follows existing SQL instrumentation approach in `instrumentation/sqlalchemy.py:58-87`
+
+**Middleware**: `ObservabilityMiddleware` no longer creates `request.state.db`. Each observability operation creates its own short-lived session.
+
+**Security**: Query operations use request-scoped sessions for RBAC/token scoping. Write operations are not RBAC-protected (observability visibility is platform-wide).
+
+**Connection Pool Sizing**: The separate session pattern creates 4-6 independent database sessions per traced request (trace start/end, span start/end, metrics, events). Default configuration (`DB_POOL_SIZE=200`, `DB_MAX_OVERFLOW=10`) provides 210 total connections, supporting ~35 concurrent traced requests. This is adequate for typical deployments. High-traffic production systems (>50 req/sec sustained) should increase pool size via environment variables: `DB_POOL_SIZE=500`, `DB_MAX_OVERFLOW=100` to support 80+ concurrent requests. Monitor for "QueuePool limit exceeded" errors and adjust pool sizing accordingly. Note: SQLite connections are capped at 50 due to file-based limitations.
+
 ## Key Environment Variables
 
 Defaults come from `mcpgateway/config.py`. `.env.example` intentionally overrides a few for local/dev convenience.
@@ -333,5 +368,6 @@ When posting PR reviews, issue comments, or any public-facing text on GitHub, us
 
 - `gh` for GitHub operations
 - `make` for build/test automation
-- `uv` for virtual environment management
-- Standard tools: pytest, black, isort, ruff, pylint
+- `uv` for virtual environment management and for `uv tool run` linter invocations
+- Dev-group tools installed in the venv: `pytest`, `mypy`, `bandit`, `pre-commit`, `prospector`, etc. (see `pyproject.toml` `[dependency-groups]`)
+- Formatters and linters (`black`, `isort`, `ruff`, `pylint`, `vulture`, `interrogate`, `radon`, `yamllint`, `tomlcheck`) are pinned in the `Makefile` and invoked on demand via `uv tool run`; always prefer the Makefile targets (`make black`, `make ruff`, `make pylint`, etc.) over calling the underlying tools directly