fix(examples): exclude the optional-peer researcher-loop from the examples typecheck

[Tjemmmic]

Problem

main CI is red and has been since #383. examples/researcher-loop/ imports @tangle-network/agent-knowledge/profiles, but #383 removed the @tangle-network/agent-knowledge peer dependency (correctly — agent-runtime's src imports it zero times; the layering is agent-knowledge -> agent-runtime). With the peer gone it is no longer installed in CI, so typecheck:examples fails on the unresolved import:

examples/researcher-loop/researcher-loop.ts(19,8): error TS2307: Cannot find module '@tangle-network/agent-knowledge/profiles'
examples/researcher-loop/synthetic-researcher.ts(14,51): error TS2307: Cannot find module '@tangle-network/agent-knowledge/profiles'

This is not cosmetic — pnpm run typecheck (which includes typecheck:examples) runs in both the merge gate (ci.yml) and the release verify (publish.yml), so the break blocks every agent-runtime merge and every publish until it is fixed.

Fix

Exclude examples/researcher-loop from tsconfig.examples.json. researcher-loop is documented in examples/README.md as the optional-peer example ("needs the optional @tangle-network/agent-knowledge peer"), and runLoop is also demonstrated by self-contained examples (driver-loop, ui-audit, supervisor-loop, runtime-run). The right move is to stop CI from typechecking an optional-peer example when that peer isn't installed — not to delete a documented example or re-add the peer #383 deliberately dropped. The example still runs for users who install agent-knowledge.

No code import references researcher-loop (only a prose cross-reference in driver-loop), so the exclude is self-contained.

Validation

Replicated the CI sequence locally (install → build → typecheck):

• pnpm install --frozen-lockfile ✓
• pnpm run build ✓
• pnpm run typecheck → exit 0 (both tsc --noEmit and typecheck:examples)
• pnpm run lint → exit 0

[tangletools]

✅ Auto-approved PR — 5764ab4d

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-25T03:09:19Z}

[Tjemmmic]

🤖 AI Code Review (ensemble)

Resolution (4d5f2de): 2 addressed.

Summary

The PR narrowly scopes an exclusion in tsconfig.examples.json to skip the researcher-loop example, which depends on an optional peer package that isn't installed. The functional change is correct, but the PR introduces inline JSON comments that are incompatible with many tools, and the examples README documentation is now stale.

Issues Found

2 total — 0 P1 (blocking) · 0 P2 (should fix) · 2 P3 (nice to have)

ℹ️ P3 — Inline JSON comments break strict JSON tooling ✅ Addressed

Note: 4d5f2de: the inline // comments are removed — tsconfig.examples.json is strict JSON again (exclude: ["node_modules", "dist", "examples/researcher-loop"]). The rationale moved to examples/README.md.

• File: tsconfig.examples.json:L11-L18
• Problem: The diff adds // line comments inside the exclude array. While tsc can parse JSONC in tsconfig files, many tools in the ecosystem (ESLint JSON parsers, json CLI, editors with strict JSON validation, prettier) will reject this file as invalid JSON. The existing file was clean JSON with no comments, so this introduces a maintenance inconsistency.
• Fix: Remove the inline comments and move the rationale into the PR description, README, or CLAUDE.md. The exclude array should simply contain: ["node_modules", "dist", "examples/researcher-loop"]

---

ℹ️ P3 — Examples README still claims full typecheck coverage ✅ Addressed

Note: 4d5f2de: examples/README.md no longer says "all of them are typechecked" — it now notes researcher-loop is excluded from typecheck:examples because it needs the optional @tangle-network/agent-knowledge peer (not installed in CI).

• File: examples/README.md
• Problem: The README documents that all examples are typechecked by pnpm run typecheck:examples, but this PR excludes researcher-loop, making the documentation inaccurate and potentially misleading to maintainers.
• Fix: Update the README to explicitly note the carve-out: Most examples are typechecked by pnpm run typecheck:examples; researcher-loop is excluded because it requires the optional @tangle-network/agent-knowledge peer.

---

✅ APPROVE

Status: the branch also regenerates the stale API reference (docs/api/runtime.md) for the already-merged onSandboxEvent tee — that docs-freshness gate was the remaining red CI step (it had been masked by the examples typecheck failure this PR fixes). With both, the full CI passes locally (typecheck, docs:check, lint).

The core config change is correct and low-risk — it prevents a typecheck failure caused by an intentionally uninstalled optional peer dependency. Only two P3 issues were found (JSON comment compatibility and stale README), neither of which warrants blocking the merge. They should be addressed as follow-up cleanup.

Quick Reference

• P3: Inline JSON comments break strict JSON tooling
• P3: Examples README still claims full typecheck coverage

---

Synthesized by Sokuza AI from multiple independent reviewers

[tangletools]

✅ Auto-approved PR — 55dc1a8b

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-25T03:28:09Z}

[Tjemmmic]

🤖 AI Code Review (ensemble)

Resolution (4d5f2de): No issues raised; independent re-review concurs, CI green.

Summary

The PR excludes the optional-peer researcher-loop example from the examples tsconfig and updates generated runtime API docs. The tsconfig change is narrowly scoped and well-commented, and the documentation diff is generated markdown with no executable behavior. No concrete blocking issues were identified.

No Issues Found

✅ APPROVE

Both reviewers and the diff confirm this is a config-only adjustment that preserves the existing typecheck contract for installed dependencies while excluding an example that depends on an optional peer package. The generated API docs add documentation for onSandboxEvent and update line-number references — no executable behavior is introduced. No P1 or P2 issues are present.

---

Synthesized by Sokuza AI from multiple independent reviewers

[tangletools]

✅ Auto-approved PR — 4d5f2deb

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-25T03:29:43Z}

[Tjemmmic]

🤖 AI Code Review (ensemble)

Resolution (4d5f2de): No issues raised; independent re-review concurs, CI green.

Summary

The PR excludes the optional-peer researcher-loop example from the examples typecheck and documents the carve-out in the examples README. The tsconfig change is correctly scoped, the README rationale is accurate, and the docs/api/runtime.md line-number updates are harmless. No correctness, security, API contract, or testing concerns.

No Issues Found

✅ APPROVE

Both independent reviewers approved the change, and the diff confirms it is narrowly scoped and consistent: the tsconfig exclude entry matches the documented exception, the README accurately explains why the optional agent-knowledge peer cannot be typechecked in CI, and no runtime behavior or production code is modified. The docs/api/runtime.md changes are generated API-doc line-number drift and pose no issue.

---

Synthesized by Sokuza AI from multiple independent reviewers