Add examples, CI, release automation, badges and a LICENSE

[TonsOfFun]

Draft — pairs with activeagents/activeagent#364, which publishes the docs these examples are linked from and holds the cross-repo suite this repo's CI runs. Merge that one first (see Notes).

Why

Two gaps, both invisible from inside the repo:

• The README shows fragments; nothing showed a concern in the shape it takes inside an app.
• There were no workflows at all — no test run on a pull request, no release automation — and the gemspec pointed at a LICENSE file that was never committed. Releases were a local rake release against a suite nobody had run.

Examples

examples/ gets one worked example per concern, laid out in Rails paths so the files can be dropped into app/ as-is:

Example	Concerns
persistent_conversation	HasContext — agent, instructions view, controller, console walkthrough
memory_handoff	HasMemory — two agent classes sharing a subject
tool_streaming	HasTools, StreamsToolUpdates, ToolCache — JSON tool template, inline DSL, ActionCable channel
reasoning	HasReasons, Reasonable
run_tracking	AgentRun, RunFingerprint, ModelPricing — service, job, polling controller
manifests	AgentManifest — a valid .agent.md plus the load/validate/convert API

test/examples_test.rb keeps them honest: every Ruby file parses, every .agent.md validates against the real validator, every SolidAgent:: constant they name exists, and every example is linked from the index.

CI and releases

• ci.yml — unit suite on Ruby 3.2/3.3/3.4, plus a cross-repo job that runs this working tree through activeagent's integration suite, against its main branch and its latest release tag, with SOLID_AGENT_STRICT=1 so nothing silently skips. This suite mocks ActiveSupport, ActiveRecord and ActionCable by design, so it can pass while the concerns no longer compose with the framework they extend — that job is what notices. Also runs nightly.
• release.yml — publishes from a v* tag via RubyGems trusted publishing (OIDC, no stored key), gated on CI, skipping versions already published. Needs a trusted publisher configured for solid_agent on rubygems.org pointing at this repo and workflow, or the push step fails with an authorization error.
• LICENSE — MIT, matching what the gemspec has always declared.
• README badges — version, downloads, CI, docs, Ruby, activeagent floor, license; plus how to run the cross-repo suite locally and how releases go out.

Bugs this turned up

• append_event dropped events under concurrency (found by Copilot's review). The read-modify-write on the events column loses an entry when two writers read before either writes — a tool loop appending progress while the run's own thread logs is exactly that. The docstring claimed concurrent appends "interleave safely", which is what re-reading buys on its own: it narrows the window, it does not close it. The read and the write now happen inside with_lock in both SolidAgent::Records::AgentRun and the install-generator template, add_log shares the same path, and three tests cover it.
• Gemfile.lock was out of sync with the gemspec on main — it recorded activeagent (>= 1.1.0) against a gemspec asking >= 1.0.0, so any frozen install refused to proceed. Nothing had ever run a deployment-mode install, so this was invisible until CI existed.
• The README's HasContext example double-persisted the user turn — it called add_conversation_user_message and then let the auto_save after_prompt callback store the same message again.
• Naming a context also names its models. has_context :conversation resolves Conversation/ConversationMessage/ConversationGeneration, not the AgentContext family solid_agent:install writes, so a fresh app raises NameError: uninitialized constant Conversation on the first request. Caught by the cross-repo suite. The README, the generator note and the example now pass class_name: and say why; rails generate solid_agent:context <name> remains the answer when separate tables are actually wanted.

Testing

• Unit suite: 238 runs, 567 assertions, 0 failures
• Record suite (real ActiveRecord): 195 runs, 494 assertions, 0 failures
• Cross-repo suite against activeagent's branch, strict: 29 runs, 98 assertions, 0 failures, 0 skips
• CI green on Ruby 3.2/3.3/3.4

Notes for review

• Merge Document SolidAgent, and test the two repos together activeagent#364 first. The integration job checks out activeagent and runs test/integration/solid_agent/ with gemfiles/solid_agent_main.gemfile; neither exists on that repo's main until #364 lands. The job skips with that reason rather than failing, so it is green here — and the latest-release entry will keep skipping until a release carries the harness.
• The Ruby floor is a promise this repo can't keep. The gemspec says >= 3.0.0, but Gemfile.lock's BUNDLED WITH 2.7.2 cannot install below 3.2, so the matrix starts at 3.2. Either raise required_ruby_version, or pin an older bundler and add the earlier versions back.
• The CI badge reads "no status" until ci.yml exists on main — expected for a first workflow.
• No lint job. This repo has no RuboCop config or dependency; adding one would bury the diff in style offenses. Worth doing separately if you want it.
• examples/ ships in the gem — the gemspec's file list excludes bin/, test/, spec/, assets/ but not examples/ or docs/. Text only, small; say the word if you'd rather exclude it.
• The release workflow assumes this gem is published after activeagent and before actionagent, matching the dependency direction.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NGn2NzpzFZT4JGKBdFMpxh

[superconductor-for-github]

⏳ Superconductor is working — View implementation

---

I'll get back to you soon!

[Copilot]

Pull request overview

This PR adds end-to-end documentation-as-code examples for SolidAgent concerns, plus CI and release automation to ensure the gem and its examples stay valid as the ecosystem evolves.

Changes:

• Add a comprehensive examples/ directory (Rails-like layout) covering core concerns (context, memory, tools/streaming/cache, reasoning, runs, manifests), with a top-level examples index.
• Add automated validation for examples/manifests via test/examples_test.rb.
• Introduce GitHub Actions workflows for CI (unit + cross-repo integration) and tag-based releases, plus README badges/updates and an MIT LICENSE.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/examples_test.rb	Adds tests to parse Ruby examples, validate manifests, and ensure examples are linked and reference existing APIs.
README.md	Adds badges, links to docs/examples, fixes/clarifies HasContext guidance, and documents CI/cross-repo testing and release flow.
LICENSE	Adds MIT license text referenced by gem metadata.
examples/README.md	Adds examples index and explains assumptions/how to run examples.
examples/persistent_conversation/usage.rb	Console walkthrough for persisted conversations.
examples/persistent_conversation/app/views/agents/support/instructions.md.erb	Example instructions template for a support agent.
examples/persistent_conversation/app/controllers/support_conversations_controller.rb	Example controller showing persisted conversation usage.
examples/persistent_conversation/app/agents/support_agent.rb	Example agent demonstrating HasContext with persistence and message replay.
examples/memory_handoff/usage.rb	Console walkthrough for long-term memory handoff.
examples/memory_handoff/app/agents/researcher_agent.rb	Example agent writing to memory (HasMemory).
examples/memory_handoff/app/agents/writer_agent.rb	Example agent reading/priming memory (HasMemory).
examples/tool_streaming/usage.rb	Console walkthrough for tools + streaming + cache usage.
examples/tool_streaming/app/views/browser_agent/tools/fetch_url.json.erb	JSON tool schema template example.
examples/tool_streaming/app/channels/tool_status_channel.rb	Example ActionCable channel for tool status streaming.
examples/tool_streaming/app/agents/browser_agent.rb	Example agent demonstrating HasTools, streaming updates, and tool caching.
examples/reasoning/usage.rb	Console walkthrough for reasoning capture/persistence.
examples/reasoning/app/agents/analysis_agent.rb	Example agent demonstrating HasReasons + persisted reasoning.
examples/run_tracking/usage.rb	Console walkthrough for run tracking, cohorts, and cost estimation.
examples/run_tracking/app/services/document_analysis_run.rb	Example service driving an AgentRun lifecycle with events.
examples/run_tracking/app/jobs/document_analysis_job.rb	Example job executing a run asynchronously.
examples/run_tracking/app/controllers/agent_runs_controller.rb	Example controller for creating/polling/cancelling runs.
examples/run_tracking/app/agents/report_agent.rb	Example agent whose executions are tracked via AgentRun + trace IDs.
examples/manifests/usage.rb	Console walkthrough for .agent.md manifest parse/validate/load/convert.
examples/manifests/changelog_writer.agent.md	Example .agent.md manifest.
.github/workflows/ci.yml	Adds unit test matrix + cross-repo integration workflow.
.github/workflows/release.yml	Adds tag-driven release workflow (build + attach + RubyGems trusted publishing).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[TonsOfFun]

Kept, but documented — leaving this thread open in case you'd rather it went the other way.

They're not decorative: this job runs activeagent's bin/test, whose config/active_agent.yml reads these at boot, and several provider clients raise when constructed without a key. activeagent's own CI sets the identical placeholders for that reason, so dropping them here would break the job rather than harden it.

On the risk you're pointing at — every generation in the cross-repo suite goes through the mock provider, which never opens a socket, and the one dashboard test uses generate_with :mock too. A code path that did reach a provider with ANTHROPIC_API_KEY=ANTHROPIC_API_KEY would get a 401 immediately: loud, free, and arguably a better failure than a mysteriously-skipped test. Wiring real secrets in would be the change that makes a live call possible.

61e8da4 adds a comment stating that, so the next reader doesn't have to re-derive it. If you'd prefer the job assert no HTTP escapes (WebMock is already in that bundle), say the word.

---

Generated by Claude Code

[TonsOfFun]

Copilot's three findings, and what changed (61e8da4):

1. append_event lost update — real bug, fixed beyond where it was flagged. The read-modify-write on the events column drops entries when two writers race, and the docstring claimed concurrent appends "interleave safely" — which is what re-reading buys on its own: it narrows the window, it does not close it. The read and the write now happen inside with_lock, in SolidAgent::Records::AgentRun and in the install generator's template alike, and add_log routes through the same helper instead of carrying its own copy of the race. Three tests added in test/records/agent_run_test.rb (stale-writer append, add_log against a concurrent event, unsaved run). activeagents/activeagent#364 mirrors it in the dummy model and corrects the same claim in the docs.

2. Net::HTTP in the browser agent example — accepted. require "net/http" added; the example is meant to survive being pasted into app/agents/.

3. Placeholder API keys in the cross-repo job — kept, now explained. They mirror activeagent's own CI, where config/active_agent.yml reads them at boot and provider clients raise when constructed without one. Every generation in that suite goes through the mock provider, so nothing reaches a network; a real call would fail loudly rather than bill anyone. Comment added saying so.

One correction on the examples_test.rb note: Module#const_defined? does accept a qualified name, so SolidAgent.const_defined?("Reasonable::Reason") resolves — the test passes today against exactly that constant. It would raise on a malformed capture (a trailing :: swept up by the regex), so that now rescues into a normal failure.

Since the first review, the branch was also rebased onto main and picked up three CI fixes worth knowing about: main's Gemfile.lock recorded activeagent (>= 1.1.0) while the gemspec asks >= 1.0.0, which no frozen install had ever exercised; Ruby 3.1 cannot install the lockfile's bundler 2.7.2, so the matrix floor is 3.2 (the gemspec still claims 3.0 — worth reconciling); and the cross-repo job now skips with a reason when the activeagent revision predates the harness, which is every release tag until one ships with it.

---

Generated by Claude Code