Engine DX/docs: asset-pipeline claim, install-generator telemetry block, gemspec Ruby floor, phantom :local backend, CHANGELOG

[TonsOfFun]

Part of an ActiveAgent + actionagent dashboard functional review (multi-agent, adversarially verified). Severity: 🟡 Minor.

A bundle of documentation/DX defects on the engine: the README claims "nothing to install, compile or configure" for assets while the engine actually requires a host asset pipeline (propshaft/sprockets) that neither README nor gemspec states; the install generator prints a top-level telemetry: YAML block the config loader silently ignores under an env-keyed file; actionagent.gemspec advertises Ruby >= 3.1.0 but the mandatory dependency chain needs >= 3.2 (install on 3.1 fails with a misleading resolver error); the docs advertise a :local (Docker) sandbox backend the engine doesn't ship (the :local default silently resolves to the in-memory mock); and the CHANGELOG dropped the released [1.3.1] heading, leaving those notes under [Unreleased].

Findings

actionagent README claims 'nothing to install, compile or configure' for assets, but neither README nor gemspec states the propshaft/sprockets requirement the engine actually has

• Where: actionagent/README.md:83 · severity: minor · kind: dx · repo: activeagent
• What breaks: The engine can only deliver its prebuilt bundles through a host asset pipeline: the assets initializer (actionagent/lib/action_agent/engine.rb:126-146) no-ops entirely when app.config does not respond to :assets, which is exactly the case in a host without propshaft or sprockets-rails (established as known issue 5 — blank dashboard, assets 404). Yet the README's Assets section asserts the opposite ('Host apps never run a JavaScript build — there is nothing to install, compile or configure') and the Install section lists only the two gems and the generator. The gemspec declares railties/activerecord/activeagent/solid_agent but no asset-pipeline gem, and the word propshaft/sprockets appears nowhere in either README, docs/, or the gemspec. A rails --api host, or any host that removed propshaft, follows the README exactly and gets a silently blank page with no pointer to the missing prerequisite.
• Evidence: grep -rin 'propshaft|sprockets|asset pipeline' actionagent/README.md README.md → no matches (exit 1); same for docs/ and actionagent/actionagent.gemspec. actionagent/README.md:82-85 ('there is nothing to install, compile or configure'). actionagent/lib/action_agent/engine.rb:130 'next unless app.config.respond_to?(:assets)'. Runtime effect already proven as known issue 5.
• Suggested fix: In actionagent/README.md, amend the Install and Assets sections to state the host must have an asset pipeline — propshaft (Rails default) or sprockets-rails — for the prebuilt bundles to be served, with an explicit note that rails --api apps need to add propshaft (and re-enable the asset initializer/middleware). Additionally, in the action_agent.assets initializer (actionagent/lib/action_agent/engine.rb:126-146), replace the silent next unless app.config.respond_to?(:assets) with a Rails.logger.warn (or deprecation-style boot warning) telling the operator the dashboard assets cannot be served without propshaft/sprockets-rails — turning the silent blank page into a diagnosable message. Optionally declare propshaft as a runtime dependency, but the warning + docs is the less invasive fix.

---

Install generator's 'Next steps' shows a top-level telemetry: block that the config loader silently ignores in a standard env-keyed active_agent.yml

• Where: actionagent/lib/generators/action_agent/install_generator.rb:106 · severity: minor · kind: dx · repo: activeagent
• What breaks: After install the generator prints: 'Configure telemetry in config/active_agent.yml:' followed by an unnested 'telemetry:\n enabled: true\n local_storage: true'. But ActiveAgent::Configuration.load does settings = config_file[env] || config_file — when the file has an environment key, only that environment's subtree is read. The framework's own active_agent:install generator creates an env-keyed file (template starts with 'development:'), so a user who pastes the printed snippet at top level (as shown) gets telemetry silently disabled: no error, no traces, an empty dashboard right after a successful install. The official docs (docs/framework/self-hosted-observability.md:151-155) nest telemetry: under the environment key, confirming the required shape the generator output omits.
• Evidence: install_generator.rb:105-108 prints the unnested snippet. lib/active_agent/configuration.rb:166 'settings = config_file[env] || config_file' (env subtree wins whenever present). lib/generators/active_agent/templates/active_agent.yml begins with 'development:' so the common file is env-keyed. docs/framework/self-hosted-observability.md:151-155 shows the correct nesting under 'production:'. Code path read end-to-end (railtie.rb:46 reads ActiveAgent.configuration[:telemetry] from that env-scoped hash).
• Suggested fix: In show_readme, print the environment-nested form: " 2. Configure telemetry in config/active_agent.yml (under each environment key, e.g. development:):" followed by " development:\n telemetry:\n enabled: true\n local_storage: true" — matching docs/framework/self-hosted-observability.md.

---

actionagent.gemspec advertises Ruby >= 3.1.0 but the mandatory dependency chain requires Ruby >= 3.2, so install on 3.1 fails with a misleading resolver error

• Where: actionagent/actionagent.gemspec:31 · severity: minor · kind: dx · repo: activeagent
• What breaks: actionagent.gemspec sets required_ruby_version '>= 3.1.0' and activeagent.gemspec sets none at all, but activeagent hard-depends on activeagents-telemetry '~> 0.1', and every published version of that gem (0.1.0 and 0.2.0 — the complete list) declares required_ruby_version '>= 3.2.0'. On Ruby 3.1 (which actionagent claims to support), bundle add actionagent / gem install actionagent cannot resolve: the failure surfaces as an activeagents-telemetry ruby-version conflict deep in resolution rather than a clear 'actionagent requires Ruby >= 3.2'. The family is internally inconsistent (solid_agent says >= 3.0, actionagent >= 3.1, telemetry >= 3.2).
• Evidence: actionagent/actionagent.gemspec:31 required_ruby_version '>= 3.1.0'; activeagent.gemspec has no required_ruby_version (grep) and declares add_dependency 'activeagents-telemetry', '~> 0.1'. Verified against the published gems: gem list -r activeagents-telemetry --all → (0.2.0, 0.1.0); gem fetch activeagents-telemetry -v 0.1.0 && gem spec ... required_ruby_version → '>= 3.2.0' for both 0.1.0 and 0.2.0.
• Suggested fix: In /home/user/activeagent: set spec.required_ruby_version = ">= 3.2.0" in both actionagent/actionagent.gemspec (line 31) and activeagent.gemspec (which currently declares none), matching activeagents-telemetry's floor — or, if Ruby 3.1 support is genuinely intended, lower activeagents-telemetry's required_ruby_version to ">= 3.1.0" and release a new telemetry version. Optionally align solid_agent's ">= 3.0.0" floor for family consistency.

---

lib/action_agent.rb documents a :local (Docker) sandbox backend that the engine does not ship; the :local default silently resolves to the in-memory mock

• Where: actionagent/lib/action_agent.rb:221 · severity: minor · kind: dx · repo: activeagent
• What breaks: Three places in the engine's public configuration docs advertise a real local sandbox backend: the module doc example 'config.sandbox_service = :local # Docker/Incus' (line 86), the accessor doc 'Sandbox service type (:local, :cloud_run, :kubernetes)' (line 174), and the sandbox_backends doc 'The engine ships :mock and :local (Docker)' (line 221-222). reset! even defaults @sandbox_service = :local (line 384). But SandboxOrchestrator::BUILT_IN_BACKENDS contains only {"mock" => "ActionAgent::MockSandboxBackend"} — its own comment says 'The engine ships only the in-memory backend' — and default_backend silently falls back to "mock" for any unregistered name. So a self-hosted operator who follows the documented config.sandbox_service = :local expecting Docker isolation gets the in-memory fake with no warning, error, or log line; sandbox 'runs' succeed against nothing real.
• Evidence: actionagent/lib/action_agent.rb:86, 174, 221-222, 384 (documented :local, default :local) vs actionagent/app/services/action_agent/sandbox_orchestrator.rb:24-31 (BUILT_IN_BACKENDS = mock only; comment 'The engine ships only the in-memory backend') and :53-55 (default_backend: backends.key?(name) ? name : "mock" — silent fallback). app/services/ contains mock_sandbox_backend.rb but no local/docker backend (ls). Code path read end-to-end.
• Suggested fix: In actionagent/lib/action_agent.rb: fix the three doc comments (86, 174, 221-222) to state the engine ships only :mock and that real backends (Docker/Incus, Cloud Run, Kubernetes) must be host-registered via ActionAgent.sandbox_backends; change the reset! default at line 384 from :local to :mock. Additionally, in sandbox_orchestrator.rb default_backend (lines 53-55), emit a Rails.logger.warn when the configured sandbox_service/SANDBOX_BACKEND names an unregistered backend before substituting "mock", so operators discover the misconfiguration instead of getting silent fake runs.

---

CHANGELOG dropped the released [1.3.1] heading; its release notes now sit under [Unreleased] with a note that is now false

• Where: CHANGELOG.md:8 · severity: minor · kind: drift · repo: activeagent
• What breaks: Commit 9b61169 (feat: pin RubyLLM's backend with a platform option #374) replaced the line '## [1.3.1] - 2026-08-19' with '## [Unreleased]' instead of inserting a new Unreleased section above it. Consequences for anyone reading the changelog of the latest release: (1) the changelog no longer records that 1.3.1 was released at all (version.rb and rubygems both say 1.3.1 is the current release); (2) the 1.3.1 fix ('Traces record the user turn an agent renders from its template') is now presented as unreleased; (3) the 'Note on the 1.3.0 gem' — 'This release contains no change relative to that published gem' — now sits inside the Unreleased section, where it is flatly wrong because Unreleased also contains the fix: load RubyLLM when the gem registers its acronym #372 RubyLLM-acronym fix and the Support Vertex AI via RubyLLM #373 platform: feature; (4) the section carries two consecutive '### Fixed' headings. A user deciding whether to upgrade from 1.3.0 gets contradictory information.
• Evidence: git show cae9407:CHANGELOG.md (the 'Release activeagent 1.3.1 (Release activeagent 1.3.1 #369)' commit) has '## [1.3.1] - 2026-08-19' at line 8; git diff cae9407..HEAD -- CHANGELOG.md shows '-## [1.3.1] - 2026-08-19' / '+## [Unreleased]' with the new Support Vertex AI via RubyLLM #373/fix: load RubyLLM when the gem registers its acronym #372 entries inserted above the retained 1.3.1 body. git log --oneline -- CHANGELOG.md shows 9b61169 is the only CHANGELOG commit after the release. lib/active_agent/version.rb: VERSION = "1.3.1"; gem list -r activeagent --all confirms 1.3.1 is published.
• Suggested fix: In /home/user/activeagent/CHANGELOG.md, keep '## [Unreleased]' at line 8 with the Support Vertex AI via RubyLLM #373 Added and fix: load RubyLLM when the gem registers its acronym #372 Fixed entries, then re-insert '## [1.3.1] - 2026-08-19' immediately before the second '### Fixed' heading (the trace-recording entry, currently ~line 33), so the trace fix and the 'Note on the 1.3.0 gem' are again attributed to the released 1.3.1. This simultaneously removes the duplicate '### Fixed' headings, since each then lives under a different version section.

Verification

Each finding above was produced by a dedicated per-feature review agent, then confirmed by an independent adversarial verifier (all rated high-confidence; zero rejected in this set). File:line citations are against the current main/HEAD of each repo; many were reproduced live against a booted dashboard.