rails-agent-stack 0.1.1

data/app/views/rails_agents/dashboard/show.html.erb

@@ -0,0 +1,139 @@
+<div class="rails-agents-embed-shell">
+  <span id="rails-agents-sync-status" class="rails-agents-sync-status rails-agents-sync-status--sr" aria-live="polite"></span>
+  <iframe
+    id="rails-agents-dashboard-frame"
+    class="rails-agents-embed"
+    src="<%= @dashboard_url %>"
+    title="Agents dashboard"
+    allow="clipboard-write"
+  ></iframe>
+</div>
+
+<script>
+  (function () {
+    var SCHEMA_URL = <%= raw rails_agents.schema_path.to_json %>;
+    var DASHBOARD_PATH = <%= raw rails_agents.dashboard_path.to_json %>;
+    var frame = document.getElementById("rails-agents-dashboard-frame");
+    var cloudOrigin = frame ? new URL(frame.src).origin : null;
+    var CSRF = document.querySelector('meta[name="csrf-token"]');
+    var statusEl = document.getElementById("rails-agents-sync-status");
+    var ALLOWED = {
+      "https://cloud.rails-agent.com": true,
+      "https://rails-agent.com": true,
+      "http://localhost:3000": true,
+      "http://127.0.0.1:3000": true,
+      "http://localhost:3001": true,
+      "http://127.0.0.1:3001": true,
+      "http://localhost:8080": true,
+      "http://127.0.0.1:8080": true
+    };
+
+    function setStatus(text, isError) {
+      if (!statusEl) return;
+      statusEl.textContent = text || "";
+      statusEl.classList.toggle("rails-agents-sync-status--error", !!isError);
+    }
+
+    function headers() {
+      var h = {
+        "Accept": "application/json",
+        "Content-Type": "application/json"
+      };
+      if (CSRF) h["X-CSRF-Token"] = CSRF.getAttribute("content");
+      return h;
+    }
+
+    async function fetchSchema() {
+      var res = await fetch(SCHEMA_URL, {
+        method: "GET",
+        credentials: "same-origin",
+        headers: headers()
+      });
+      var json = {};
+      try { json = await res.json(); } catch (e) { json = {}; }
+      if (!res.ok || json.ok === false) {
+        throw new Error(json.error || ("Schema failed (" + res.status + ")"));
+      }
+      return json;
+    }
+
+    function syncBrowserUrl(data) {
+      if (!data.path || data.path.indexOf("/dashboard") !== 0) return;
+      var suffix = data.path.slice("/dashboard".length);
+      var next = DASHBOARD_PATH + suffix;
+      if (data.search) next += "?" + data.search;
+      if (data.hash) next += data.hash;
+      var current = window.location.pathname + window.location.search + window.location.hash;
+      if (next !== current) {
+        window.history.replaceState({ railsAgentsDashboard: true }, "", next);
+      }
+    }
+
+    function syncFrameFromBrowser() {
+      if (!frame || !frame.contentWindow || !cloudOrigin) return;
+      if (window.location.pathname.indexOf(DASHBOARD_PATH) !== 0) return;
+      var suffix = window.location.pathname.slice(DASHBOARD_PATH.length);
+      frame.contentWindow.postMessage({
+        type: "rails-agents:navigate-to",
+        path: "/dashboard" + suffix,
+        search: window.location.search.replace(/^\?/, ""),
+        hash: window.location.hash
+      }, cloudOrigin);
+    }
+
+    window.addEventListener("popstate", syncFrameFromBrowser);
+
+    window.addEventListener("message", function (event) {
+      if (!ALLOWED[event.origin]) return;
+      var data = event.data || {};
+
+      if (data.type === "rails-agents:navigate") {
+        syncBrowserUrl(data);
+        return;
+      }
+
+      if (data.type === "rails-agents:schema") {
+        fetchSchema()
+          .then(function (result) {
+            if (event.source && event.source.postMessage) {
+              event.source.postMessage({
+                type: "rails-agents:schema-result",
+                requestId: data.requestId,
+                ok: true,
+                tables: result.tables || [],
+                adapter: result.adapter,
+                databases: result.databases || [],
+                configFiles: result.config_files || []
+              }, event.origin);
+            }
+          })
+          .catch(function (err) {
+            if (event.source && event.source.postMessage) {
+              event.source.postMessage({
+                type: "rails-agents:schema-result",
+                requestId: data.requestId,
+                ok: false,
+                error: err.message || "Schema failed",
+                tables: []
+              }, event.origin);
+            }
+          });
+        return;
+      }
+
+      // Deprecated: cloud-to-local authoring pull. Use `rails-agents sync` (local → cloud)
+      // or scaffold agents with `rails generate rails_agents:agent`. See AGENTS.md.
+      if (data.type === "rails-agents:pull") {
+        if (event.source && event.source.postMessage) {
+          event.source.postMessage({
+            type: "rails-agents:pull-result",
+            requestId: data.requestId,
+            ok: false,
+            error: "Cloud pull is deprecated. Build agents locally (see AGENTS.md) and run rails-agents sync."
+          }, event.origin);
+        }
+        setStatus("Cloud pull deprecated — edit app/agents/ locally", true);
+      }
+    });
+  })();
+</script>

data/app/views/rails_agents/registrations/new.html.erb

@@ -0,0 +1,83 @@
+<%
+  @step ||= :email
+  @workspace ||= (Rails.application.class.module_parent_name rescue "MyApp")
+  @github_url ||= "#"
+%>
+<div class="rails-agents-connect">
+  <%= render "rails_agents/shared/auth_brand" %>
+
+  <section class="rails-agents-connect__form-pane">
+    <div class="rails-agents-connect__card">
+      <% if notice.present? %>
+        <div class="rails-agents-flash"><%= notice %></div>
+      <% end %>
+      <% if alert.present? %>
+        <div class="rails-agents-flash rails-agents-flash--alert"><%= alert %></div>
+      <% end %>
+
+      <h2>Create workspace</h2>
+      <p class="rails-agents-lede">
+        Links this Rails app to your company workspace — build agents in
+        <code>app/agents/</code>, attach BYOK credentials in the cloud dashboard.
+      </p>
+
+      <% if @step.to_sym == :code %>
+        <p class="rails-agents-muted" style="margin-top:1.25rem">
+          Enter the code we sent to <strong><%= @email %></strong>
+        </p>
+        <% if @dev_code.present? %>
+          <p class="rails-agents-flash" style="margin-top:0.75rem">
+            Dev code: <code><%= @dev_code %></code>
+          </p>
+        <% end %>
+
+        <%= form_with url: rails_agents.signup_verify_path, method: :post, local: true, class: "rails-agents-form", html: { style: "margin-top:1rem" } do %>
+          <label>
+            Code
+            <input type="text" name="code" inputmode="numeric" pattern="\d{4}" maxlength="4" required autofocus autocomplete="one-time-code" placeholder="0000" />
+          </label>
+          <button type="submit" class="rails-agents-btn rails-agents-btn--primary">
+            Verify &amp; connect →
+          </button>
+        <% end %>
+
+        <p class="rails-agents-connect__foot">
+          <%= link_to "Use a different email", rails_agents.signup_path %>
+        </p>
+      <% else %>
+        <a class="rails-agents-btn rails-agents-btn--ghost rails-agents-btn--spaced"
+           href="<%= @github_url %>">
+          <svg class="rails-agents-github-icon" viewBox="0 0 16 16" aria-hidden="true">
+            <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>
+          </svg>
+          Continue with GitHub
+        </a>
+
+        <div class="rails-agents-divider">or email</div>
+
+        <%= form_with url: rails_agents.signup_path, method: :post, local: true, class: "rails-agents-form" do %>
+          <label>
+            Workspace
+            <input type="text" name="workspace" value="<%= @workspace %>" autocomplete="organization" />
+          </label>
+          <label>
+            Your name <span>(optional)</span>
+            <input type="text" name="name" value="<%= @name %>" autocomplete="name" />
+          </label>
+          <label>
+            Email
+            <input type="email" name="email" value="<%= @email %>" required autocomplete="email" placeholder="you@company.com" />
+          </label>
+          <button type="submit" class="rails-agents-btn rails-agents-btn--primary">
+            Continue with email
+          </button>
+        <% end %>
+
+        <p class="rails-agents-connect__foot">
+          Already have an account?
+          <%= link_to "Sign in", rails_agents.signin_path %>
+        </p>
+      <% end %>
+    </div>
+  </section>
+</div>

data/app/views/rails_agents/sessions/new.html.erb

@@ -0,0 +1,73 @@
+<%
+  @step ||= :email
+  @github_url ||= "#"
+%>
+<div class="rails-agents-connect">
+  <%= render "rails_agents/shared/auth_brand" %>
+
+  <section class="rails-agents-connect__form-pane">
+    <div class="rails-agents-connect__card">
+      <% if notice.present? %>
+        <div class="rails-agents-flash"><%= notice %></div>
+      <% end %>
+      <% if alert.present? %>
+        <div class="rails-agents-flash rails-agents-flash--alert"><%= alert %></div>
+      <% end %>
+
+      <h2>Sign in</h2>
+      <p class="rails-agents-lede">
+        Jump back into your workspace — nothing to reinstall.
+      </p>
+
+      <% if @step.to_sym == :code %>
+        <p class="rails-agents-muted" style="margin-top:1.25rem">
+          Enter the code we sent to <strong><%= @email %></strong>
+        </p>
+        <% if @dev_code.present? %>
+          <p class="rails-agents-flash" style="margin-top:0.75rem">
+            Dev code: <code><%= @dev_code %></code>
+          </p>
+        <% end %>
+
+        <%= form_with url: rails_agents.signin_verify_path, method: :post, local: true, class: "rails-agents-form", html: { style: "margin-top:1rem" } do %>
+          <label>
+            Code
+            <input type="text" name="code" inputmode="numeric" pattern="\d{4}" maxlength="4" required autofocus autocomplete="one-time-code" placeholder="0000" />
+          </label>
+          <button type="submit" class="rails-agents-btn rails-agents-btn--primary">
+            Verify &amp; connect →
+          </button>
+        <% end %>
+
+        <p class="rails-agents-connect__foot">
+          <%= link_to "Use a different email", rails_agents.signin_path %>
+        </p>
+      <% else %>
+        <a class="rails-agents-btn rails-agents-btn--ghost rails-agents-btn--spaced"
+           href="<%= @github_url %>">
+          <svg class="rails-agents-github-icon" viewBox="0 0 16 16" aria-hidden="true">
+            <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/>
+          </svg>
+          Continue with GitHub
+        </a>
+
+        <div class="rails-agents-divider">or email</div>
+
+        <%= form_with url: rails_agents.signin_path, method: :post, local: true, class: "rails-agents-form" do %>
+          <label>
+            Email
+            <input type="email" name="email" value="<%= @email %>" required autocomplete="email" placeholder="you@company.com" />
+          </label>
+          <button type="submit" class="rails-agents-btn rails-agents-btn--primary">
+            Continue with email
+          </button>
+        <% end %>
+
+        <p class="rails-agents-connect__foot">
+          New here?
+          <%= link_to "Create workspace", rails_agents.signup_path %>
+        </p>
+      <% end %>
+    </div>
+  </section>
+</div>

data/app/views/rails_agents/shared/_auth_brand.html.erb

@@ -0,0 +1,20 @@
+<aside class="rails-agents-connect__brand">
+  <a class="rails-agents-logo-lockup" href="https://rails-agent.com" target="_blank" rel="noopener">
+    <span class="rails-agents-logo-mark" aria-hidden="true">RA</span>
+    <span class="rails-agents-logo-word">Rails <em>Agent</em></span>
+  </a>
+
+  <div class="rails-agents-connect__copy">
+    <h1>Fullstack agents for <em>Rails</em>.</h1>
+    <p>
+      Connect your company workspace, build agents in <code>app/agents/</code>
+      with your editor or external coding agent, then test, deploy, and monitor at
+      <code>/agents</code>.
+    </p>
+    <p class="rails-agents-muted">
+      Start with <strong>AGENTS.md</strong> in your repo — first step: a database Knowledge agent.
+    </p>
+  </div>
+
+  <p class="rails-agents-connect__meta">rails-agent.com</p>
+</aside>

data/config/routes.rb

@@ -0,0 +1,34 @@
+RailsAgents::Engine.routes.draw do
+  # First-run default: create workspace. Already connected → signup redirects to dashboard.
+  root to: "registrations#new"
+
+  get "signup", to: "registrations#new", as: :signup
+  post "signup", to: "registrations#create"
+  post "signup/verify", to: "registrations#verify", as: :signup_verify
+
+  get "signin", to: "sessions#new", as: :signin
+  post "signin", to: "sessions#create"
+  post "signin/verify", to: "sessions#verify", as: :signin_verify
+  delete "signout", to: "sessions#destroy", as: :signout
+
+  post "handshake", to: "handshake#create", as: :handshake
+  get "connect", to: "connect#show", as: :connect
+
+  # Deprecated compatibility: cloud-to-local pull (prefer local scaffold + `rails-agents sync`)
+  post "pull", to: "pulls#create", as: :pull
+
+  # ActiveRecord schema for Knowledge agents / database connector in dashboard
+  get "schema", to: "schema#show", as: :schema
+
+  # Production runtime → Rails tool execution. The bearer token is
+  # introspected against Rails Agent Cloud before any local code runs.
+  post "bridge/:agent/tools/:tool", to: "tool_bridge#create", as: :tool_bridge
+
+  # Open-Wire reverse path (channel → agent). No separate OpenWire::Engine mount.
+  # Gateway POSTs message.inbound here; gem open-wire verifies + parses.
+  post "open_wire/inbound", to: "open_wire_inbound#create", as: :open_wire_inbound
+  post "open_wire/inbound/:agent", to: "open_wire_inbound#create", as: :open_wire_inbound_agent
+
+  get "dashboard", to: "dashboard#show", as: :dashboard
+  get "dashboard/*path", to: "dashboard#proxy", as: :dashboard_proxy
+end

data/docs/AGENTS.md

@@ -0,0 +1,220 @@
+# AGENTS.md — Rails Agent onboarding
+
+Guide for **external coding agents** (Cursor, Claude Code, Codex, etc.) and humans building on Rails Agent.
+
+## What this platform is
+
+Rails Agent is a **fullstack agent platform for Rails**: you write agents as Ruby directories under `app/agents/`, connect provider credentials (BYOK) in the cloud dashboard, then **test, deploy, and monitor** at `/agents`.
+
+Billing: **fixed company subscription** + **metered usage at provider/infrastructure cost** + **transparent 1% service fee**.
+
+## Agent taxonomy (pick one)
+
+| Type | Main purpose | Example |
+|------|--------------|---------|
+| **Knowledge** | Understand and answer | Order support from Rails data and policy docs |
+| **Workflow** | Execute predictable processes | Verify → approve → refund → notify |
+| **Operations** | Coordinate unpredictable real-world work | Incident or customer escalation coordination |
+| **Monitoring** | Observe changes and respond | Inventory, error, or SLA watcher |
+
+Use the matching base class: `RailsAgents::KnowledgeAgent`,
+`WorkflowAgent`, `OperationsAgent`, or `MonitoringAgent`.
+
+Legacy aliases (deprecated): `ChatAgent` → Knowledge, `BackgroundAgent` → Operations.
+
+## Run response schema (integrate into product)
+
+Every provider (OpenAI, Anthropic, Gateway, OSS) normalizes to one shape.
+Your app should not branch on provider-specific payloads.
+
+| Field | Use |
+|-------|-----|
+| `result.output_text` | Final Markdown answer for chat / email / Slack |
+| `result.output` | Legacy alias for `output_text` |
+| `result.output_data` | Optional structured Hash for Rails branching (`nil` if text-only) |
+| `result.items` | Typed turn: `message` (+ `result` when `output_data` present) |
+| `result.format` | Always `"markdown"` for message content |
+| `result.trace` | Tools / debug — Monitor, not the product answer |
+
+```ruby
+result = StoreAssistant.run("Where is ORD-1001?", session_id: "user-1")
+puts result.output_text
+payload = result.output_data  # Hash or nil
+```
+
+Consumption by taxonomy:
+
+- **Knowledge** — render Markdown (`output_text`); tables for catalogs
+- **Workflow** — show `output_text`; branch on `output_data` (status, ids)
+- **Operations** — post `output_text`; handoff via `output_data`
+- **Monitoring** — alert with `output_text`; automate from `output_data`
+
+Public docs: https://rails-agent.com/docs/run-response
+
+## Progressive path
+
+### 1. Connect workspace
+
+```bash
+bundle add rails-agent-stack
+bin/rails generate rails_agents:install
+bin/dev   # open http://localhost:3000/agents
+```
+
+Sign up / connect at `/agents`. Platform API key is written to `config/rails_agents_credentials.yml` — **not** your OpenAI/Anthropic keys.
+
+### 2. First agent: database Knowledge (fastest win)
+
+```bash
+bin/rails generate rails_agents:agent store_assistant --type knowledge --database
+bin/rails db:seed   # if demo data exists
+```
+
+Edit `app/agents/store_assistant/agent.rb` — tools call your ActiveRecord models. Attach BYOK in cloud dashboard → **Settings → Providers** (reference name e.g. `:company_openai`).
+
+```ruby
+class StoreAssistant < RailsAgents::KnowledgeAgent
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation, provider: :mem0, recall: 5
+
+  tool :lookup_order do |order_number:|
+    # wire to your models
+  end
+end
+```
+
+Test locally:
+
+```bash
+bundle exec rails-agents run store_assistant "Where is order ORD-DEMO-1001?"
+bundle exec rails-agents sync store_assistant
+```
+
+Dashboard uses `GET /agents/schema` to discover tables for database setup — keep that endpoint available.
+
+### 3. Tools
+
+Add Ruby tool blocks in `agent.rb` or files under `tools/`. Tools run in your Rails app context.
+Start with one read-only tool and test it before adding side effects.
+
+### Workspace Library (share only when reuse is real)
+
+Agent-specific capabilities stay under `app/agents/<slug>/`. Capabilities used
+by multiple agents have one canonical source under:
+
+```text
+app/agents_library/
+├── tools/
+├── skills/
+├── packages/
+├── knowledge/
+└── connectors/
+```
+
+Attach shared sources through `app/agents/<slug>/imports.yml`:
+
+```yaml
+version: 1
+imports:
+  - kind: skill
+    slug: triage
+    from: library/skills/triage.rb
+  - kind: knowledge
+    slug: shipping_policy
+    from: library/knowledge/shipping_policy.md
+  - kind: package
+    slug: frontend_design
+    from: library/packages/frontend_design
+```
+
+`bundle exec rails-agents sync NAME` safely resolves these paths and includes
+them in the agent bundle. It fails on path traversal, missing sources, or a
+conflict with an agent-local file. This keeps the Library canonical without
+duplicating generated copies in Git.
+
+Shared Ruby tool files are organization boundaries, not a new DSL. Register the
+tool in `agent.rb` using the normal `tool` block and call the shared module or
+service from that block.
+
+### 4. Connectors
+
+Add external SaaS integrations via Connect in the cloud dashboard (OAuth-managed actions). Use a local Ruby tool for your own database; use a connector for systems such as Notion, Sheets, or HubSpot.
+
+### 5. Skills
+
+Composable behaviors in `skills/` — reference with `skill :name, from: "skills/name.rb"`.
+
+### 5b. Packages (agentic package manager)
+
+**Package** is the installable primitive. Search Skills.sh, Microsoft APM, and
+Smithery from the dashboard (**Library → Packages** or agent **Build → Packages**),
+or via CLI:
+
+```bash
+bundle exec rails-agents packages "refund"
+bundle exec rails-agents add-package skills_sh:owner/repo/skill \
+  --registry skills_sh --agent store_assistant --source owner/repo
+```
+
+Rails Agent downloads the upstream package, converts it into:
+
+```text
+app/agents/<slug>/packages/<name>/package.yml
+app/agents/<slug>/packages/<name>/SKILL.md
+app/agents/<slug>/skills/<name>.rb      # capability ready immediately
+```
+
+and can save it to the workspace Library like tools/skills/plugins.
+
+| Primitive | Meaning |
+|-----------|---------|
+| **Tool** | One deterministic Ruby action |
+| **Skill** | Multi-step playbook (how to do work) |
+| **Package** | Installable capability from external registries |
+| **Connector** | External SaaS (OAuth Connect) |
+| **Knowledge** | Docs / DB sources for grounding |
+| **Library** | Workspace reuse of any of the above |
+
+### 6. Playbooks
+
+Clone a Playbook when you want a proven starting structure, then customize the generated files locally. Playbooks can combine instructions, tools, and skills.
+
+### 7. Channels
+
+Scaffold stubs live in `channels/`. Install connectors from `/agents` dashboard (Slack, web chat, API, cron, etc.).
+
+### 8. Evals
+
+Add cases under `evals/*.yml`. Run on deploy from dashboard or `bundle exec rails-agents evals NAME`.
+
+### 9. Deploy & monitor
+
+```bash
+bundle exec rails-agents deploy store_assistant
+bundle exec rails-agents logs store_assistant
+bundle exec rails-agents traces store_assistant
+```
+
+Use `/agents` for runs, cost, traces, and eval results.
+
+## Model DSL (BYOK)
+
+```ruby
+# Explicit provider + cloud credential reference (no secrets in repo)
+model :gpt_5_mini, provider: :openai, credential: :company_openai
+
+# Legacy cloud-routed (still supported, not default in new scaffolds)
+model :auto
+```
+
+Credential symbols map to encrypted records in Rails Agent Cloud — never commit API keys.
+
+## Do not use (deprecated)
+
+- **Chat authoring / cloud pull** — build locally; push with `rails-agents sync`. CLI `pull` remains for compatibility only.
+
+## References
+
+- Gem README: [README.md](README.md)
+- Product spec: [docs/PRD.md](docs/PRD.md)
+- Website: https://rails-agent.com/docs/getting-started

data/docs/PRD.md

@@ -0,0 +1,89 @@
+# Rails Agent — Product Requirements Document
+
+> **`rails-agent-stack` gem** (OSS, mounts into Rails) + **Rails Agent Cloud** (managed backend). Build agents locally with docs and external coding agents; test, deploy, and monitor at `/agents`.
+
+## 1. Mission
+
+Make Rails Agent the **fullstack agentic platform for Rails**: developers scaffold agents in `app/agents/`, attach **BYOK** model credentials in the cloud, and use `/agents` to test, deploy, and monitor — with clear docs (**AGENTS.md**) for humans and external coding agents.
+
+## 2. Core Philosophy
+
+1. **Documentation-first** — AGENTS.md progressive path; no chat-based authoring.
+2. **Build in the repo** — Ruby agent directories, generators, external coding agents.
+3. **BYOK models** — provider credentials stored encrypted in cloud; referenced from agent DSL.
+4. **Four taxonomy types** — Knowledge, Workflow, Operations, Monitoring.
+5. **Test → deploy → monitor in one place** — `/agents` dashboard embed.
+6. **Transparent company billing** — fixed subscription + pass-through usage + 1% service fee.
+
+## 3. Product Surface
+
+### 3.1 `rails-agent-stack` gem
+
+- Install: `bundle add rails-agent-stack` + `rails generate rails_agents:install`.
+- Mountable engine at `/agents`: signup, connect, dashboard embed, **schema bridge** for DB setup.
+- Agent-as-directory under `app/agents/<name>/`.
+- **Product-facing taxonomy classes**: `KnowledgeAgent`, `WorkflowAgent`, `OperationsAgent`, `MonitoringAgent`.
+- **DSL**:
+
+```ruby
+class StoreAssistant < RailsAgents::KnowledgeAgent
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation
+  knowledge_from "knowledge/**/*"
+
+  tool :lookup_order do |order_number:|
+    Order.find_by(number: order_number).as_json
+  end
+
+  channel :web
+end
+```
+
+- **CLI**: install, new, run, sync, deploy, logs, traces, evals. `pull` deprecated.
+- **Generator**: `--type`, `--database` for first database Knowledge agent.
+- Runtime: thin client to cloud for inference, deploys, observability. Tools execute in Rails app context.
+
+### 3.2 Rails Agent Cloud
+
+- Auth, workspaces (company-scoped), API keys.
+- **Credential vault** for BYOK (OpenAI, Anthropic, etc.) — referenced by symbol from agents.
+- Model gateway resolves agent model + credential ref.
+- Deploys, channels, vector/RAG, evals, traces, billing.
+- **Billing**: Stripe company subscription + metered usage at cost + 1% service fee.
+- API: runs, deploys, knowledge sync, files sync, logs, traces, evals.
+
+### 3.3 Dashboard
+
+- Workspace: agents list, config (model/credential, tools, skills, memory, knowledge, channels, evals, deploy).
+- **No Kip / chat authoring** — configuration and monitoring UI only.
+- Schema discovery via parent page `GET /agents/schema`.
+
+## 4. Pricing
+
+- **Company subscription** — fixed monthly fee per workspace (production).
+- **Metered usage** — provider tokens and infrastructure at **pass-through cost**.
+- **Service fee** — **1%** on metered usage, shown transparently on invoices.
+- Sandbox/dev tier for building (non-production traffic).
+
+## 5. Non-Goals
+
+- Chat-based agent authoring (removed).
+- Storing provider API keys in the Rails app repo.
+- Self-hosting / on-prem (cloud runtime).
+- Non-Rails frameworks.
+
+## 6. Milestones
+
+1. **M1 — Gem + docs**: install, AGENTS.md, taxonomy, BYOK DSL, `--database` generator.
+2. **M2 — Cloud BYOK + billing**: credential vault, company plans, usage metering + 1%.
+3. **M3 — Channels + deploy**: Slack, web, API, cron end-to-end.
+4. **M4 — GA**: evals, monitoring agents, plugins/skills/playbooks in dashboard.
+
+## 7. SEO / Brand
+
+- Name: **Rails Agent** / `rails-agent-stack`.
+- Tone: confident, plainspoken, Rails-native.
+
+---
+
+**Instruction to implementers**: Gem and boilerplate follow this doc. Cloud dashboard must remove authoring chat and implement BYOK + company billing.

data/examples/support/agent.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Support < RailsAgents::KnowledgeAgent
+  model :gpt_5_mini, provider: :openai, credential: :company_openai
+  memory :conversation
+  knowledge_from "knowledge/**/*"
+
+  tool :lookup_order do |order_id:|
+    { id: order_id, status: "shipped", note: "Example only � wire to your Order model." }
+  end
+
+  skill :triage, from: "skills/triage.rb"
+  channel :slack
+end