v2.0 - studio UI

.dockerignore

@@ -0,0 +1,49 @@
+# =============================================================================
+# Docker build context exclusions.
+#
+# Without this the context includes node_modules (Studio), bin/obj (six .NET
+# projects), the Astro build output and git history — hundreds of MB that are
+# never used by an image build and that invalidate the layer cache on every
+# unrelated edit. Package *manifests* are deliberately NOT excluded: npm ci and
+# dotnet restore both need them.
+# =============================================================================
+
+.git
+.gitignore
+.github
+.opencode
+**/.vs
+**/.vscode
+**/node_modules
+**/bin
+**/obj
+**/.vite
+**/test-results
+**/playwright-report
+**/.astro
+**/.pytest_cache
+
+# Build outputs — the image builds these itself.
+src/hercules-studio/dist
+src/hercules-web/dist
+
+# Runtime state. HERCULES_DATA_ROOT is pinned inside the container, so a host
+# data directory must never leak in and silently seed the test instance.
+data
+**/data
+*.db
+*.db-shm
+*.db-wal
+
+# Docs and assets not needed to run the agent.
+docs
+assets
+examples
+templates
+deploy/raspberry-pi
+
+# Not needed at runtime.
+**/*.md
+!**/README.md
+LICENSE
+LICENSE-COMMERCIAL.md

.gitattributes

@@ -0,0 +1,11 @@
+# The `openapi` CI job regenerates openapi.json and fails on any diff, including
+# line-ending-only changes. `core.autocrlf` is a per-machine Git setting, so without
+# pinning this the job's result depends on whichever contributor pushed — a checkout
+# with autocrlf=false produces CRLF, a Linux runner produces LF, and the job fails on
+# content that is byte-identical apart from newlines.
+#
+# Both files below are generated artefacts that are committed and diffed, so their line
+# endings are pinned rather than left to autocrlf.
+
+src/agent/Hercules.WebApi/openapi.json            text eol=lf
+src/hercules-studio/renderer/src/sdk/openapi.d.ts text eol=lf

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
-  - name: 💬 Вопросы и обсуждения
-    url: https://github.com/discussions
-    about: Задайте вопрос или обсудите идею в Discussions
-  - name: 🔒 Уязвимости безопасности
-    url: https://github.com/security/advisories
-    about: Сообщайте об уязвимостях приватно (см. SECURITY.md)
+  - name: Security issue
+    about: Please report security vulnerabilities privately via SECURITY.md.
+    url: https://github.com/techbuzzz/Hercules/security/advisories
+  - name: Question
+    about: Ask a question in Discussions.
+    url: https://github.com/techbuzzz/Hercules/discussions

.github/ISSUE_TEMPLATE/good-first-discord.yml

@@ -0,0 +1,29 @@
+name: Add Discord bot
+description: Add a second chat interface — Discord bot alongside Telegram.
+labels: ["good first issue", "interface", "discord"]
+title: "[Good first issue] Add Discord bot interface"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Hercules already has a Telegram bot (`src/agent/Hercules/Telegram/TelegramBot.cs`).
+        This issue asks for the same idea implemented for Discord.
+  - type: checkboxes
+    id: tasks
+    attributes:
+      label: Checklist
+      options:
+        - label: Read existing `TelegramBot.cs` to understand the adapter pattern
+        - label: Add a new project reference or package for Discord (e.g., `Discord.Net`)
+        - label: Implement `DiscordBot.cs` under `src/agent/Hercules/Discord/`
+        - label: Wire it into `Program.cs` behind `--discord` CLI flag
+        - label: Add config section `Discord: { Enabled, Token }` to `appsettings.json`
+        - label: Add minimal README in `docs/` or update `examples/`
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Tips for the implementer.
+      value: |
+        Reuse `AgentCore` via `WebApiAdapter` or call directly.
+        Keep parity with Telegram commands: `/start`, `/skills`, `/profile`, `/reset`.

.github/ISSUE_TEMPLATE/good-first-dockerfile.yml

@@ -0,0 +1,32 @@
+name: Add Dockerfile
+description: Provide a production-ready Dockerfile for Hercules (not only edge Raspberry Pi).
+labels: ["good first issue", "ops", "docker"]
+title: "[Good first issue] Add main Dockerfile and compose for Hercules"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        There is an edge Dockerfile under `deploy/raspberry-pi/`. This issue is about adding
+        a generic, non-privileged Dockerfile for the main agent and Web API.
+  - type: checkboxes
+    id: tasks
+    attributes:
+      label: Checklist
+      options:
+        - label: Read `deploy/raspberry-pi/Dockerfile` for conventions
+        - label: Add `Dockerfile` at repo root (or `deploy/default/Dockerfile`)
+        - label: Multi-stage build: restore → build → runtime (Alpine or Debian-slim)
+        - label: Add `.dockerignore`
+        - label: Add `docker-compose.yml` with optional Redis/PostgreSQL profiles
+        - label: Document build/run commands in README
+        - label: Add a GitHub Actions job that builds the image
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Non-functional requirements.
+      value: |
+        Use non-root user.
+        Expose ports 8421 (Web API) and optionally 4321 (frontend static).
+        Mount `data/` as a volume.
+        Keep image size small.

.github/ISSUE_TEMPLATE/good-first-openrouter.yml

@@ -0,0 +1,30 @@
+name: Add OpenRouter adapter
+description: Add OpenRouter as a supported LLM provider.
+labels: ["good first issue", "llm", "provider"]
+title: "[Good first issue] Add OpenRouter LLM provider adapter"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for picking this up! OpenRouter exposes an OpenAI-compatible endpoint,
+        so the change is usually a new client class + registration in `LlmClientFactory`.
+  - type: checkboxes
+    id: tasks
+    attributes:
+      label: Checklist
+      options:
+        - label: Read [docs/CONFIGURATION-EN.md](docs/CONFIGURATION-EN.md)
+        - label: Implement `OpenRouterClient.cs` under `src/agent/Hercules/LLM/`
+        - label: Add "openrouter" to `LlmClientFactory` and `AppConfig`
+        - label: Add config section example to `appsettings.json`
+        - label: Add a unit test in `tests/Hercules.Agent.Tests/LLM/`
+        - label: Update README provider table
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Useful links or hints for the implementer.
+      value: |
+        Endpoint: `https://openrouter.ai/api/v1`
+        Docs: https://openrouter.ai/docs
+        Similar existing clients: `YandexGPTClient.cs`, `LocalLLMClient.cs`

.github/ISSUE_TEMPLATE/good-first-readme-ru.yml

@@ -0,0 +1,31 @@
+name: Translate README to Russian
+description: Bring README-RU.md up to parity with the new landing-style README.md.
+labels: ["good first issue", "docs", "i18n"]
+title: "[Good first issue] Translate new README landing page to Russian"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The English README was upgraded to a landing page with badges, architecture diagram,
+        comparison table, quick start, and CTA. The Russian version needs the same refresh.
+  - type: checkboxes
+    id: tasks
+    attributes:
+      label: Checklist
+      options:
+        - label: Read the new [README.md](../README.md) top section
+        - label: Update [README-RU.md](../README-RU.md) with the same landing structure
+        - label: Keep all existing Russian sections that are still accurate
+        - label: Translate the ASCII architecture diagram
+        - label: Translate the comparison table (Hercules vs Hermes vs AutoGen)
+        - label: Update links so they point to the Russian docs where available
+        - label: Open a PR with `docs:` prefix
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Style guide.
+      value: |
+        Keep technical terms consistent with existing Russian docs.
+        Do not translate code snippets or CLI commands.
+        Ask for review if unsure about terminology.

.github/ISSUE_TEMPLATE/good-first-web-search.yml

@@ -0,0 +1,29 @@
+name: Add web-search skill
+description: Add a reusable `web-search` skill that queries a search engine and summarizes results.
+labels: ["good first issue", "skill", "tools"]
+title: "[Good first issue] Implement web-search skill"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Hercules has an `http` tool. This issue is about wrapping it into a first-class skill
+        that can answer "search the web for ..." and return a concise summary.
+  - type: checkboxes
+    id: tasks
+    attributes:
+      label: Checklist
+      options:
+        - label: Pick a search provider: DuckDuckGo HTML, Bing API, SerpApi, or SearXNG
+        - label: Create `data/Skills/skill.web-search.md` following the skill spec
+        - label: Add allow-list entries for the search endpoint in `appsettings.json`
+        - label: Test at least 3 queries in CLI REPL
+        - label: Document the skill in `examples/03-local-folder-rag` or a new `examples/06-web-search`
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Implementation hints.
+      value: |
+        DuckDuckGo HTML endpoint is a good free starting point.
+        Parse the HTML carefully or use a lightweight library.
+        Cite sources in the final summary.

.github/opencode.jsonc

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "MSDN": {
+	  "type": "remote",
+      "url":"https://learn.microsoft.com/api/mcp",
+      "enabled": true,
+    },
+	"context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  },
+}
+

.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Cancel superseded runs on the same ref — this suite is fast enough that a stale
+# result is worth less than the minutes it costs to keep computing it.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  DOTNET_NOLOGO: "true"
+  DOTNET_CLI_TELEMETRY_OPTOUT: "true"
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: "true"
+
+jobs:
+  agent:
+    name: Agent (.NET)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+
+      - name: Restore
+        run: dotnet restore src/agent/Hercules.slnx
+
+      - name: Build
+        run: dotnet build src/agent/Hercules.slnx -c Release --no-restore
+
+      - name: Test
+        run: >-
+          dotnet test tests/Hercules.Agent.Tests
+          -c Release --no-build
+          --logger "trx;LogFileName=agent-tests.trx"
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-test-results
+          path: "**/TestResults/*.trx"
+          if-no-files-found: ignore
+
+  openapi:
+    name: OpenAPI document is current
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          global-json-file: global.json
+
+      # Studio's contract test (client.contract.test.ts) asserts every endpoint the
+      # client calls exists in the committed document. During the web-first migration
+      # that document was found stale — live routes were missing from it and only
+      # regeneration exposed that. This job makes the drift fail the build instead.
+      - name: Regenerate the document
+        run: dotnet build src/agent/Hercules.WebApi -p:OpenApiGenerateDocumentOnBuild=true
+
+      - name: Fail if the committed document drifted
+        run: |
+          if ! git diff --quiet -- src/agent/Hercules.WebApi/openapi.json; then
+            echo "::error::src/agent/Hercules.WebApi/openapi.json is stale. Regenerate and commit it with:"
+            echo "  dotnet build src/agent/Hercules.WebApi -p:OpenApiGenerateDocumentOnBuild=true"
+            echo "  cd src/hercules-studio && npm run generate:api"
+            git --no-pager diff -- src/agent/Hercules.WebApi/openapi.json | head -120
+            exit 1
+          fi
+
+  studio:
+    name: Studio (Node)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: src/hercules-studio
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: src/hercules-studio/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      # The Playwright config starts its own preview server; agent calls are
+      # stubbed in-spec, so no Hercules agent is needed here.
+      - name: E2E tests
+        run: npm run test:e2e
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: src/hercules-studio/playwright-report
+          if-no-files-found: ignore
+          retention-days: 7