secretpray · Nov 6, 2026 · Nov 3, 2026 · Nov 3, 2026
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,25 @@
+version: 2
+
+# Development happens on `next` until the new API is released; switch
+# target-branch back to `main` when `next` is merged.
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    target-branch: next
+    schedule:
+      interval: weekly
+    # Supply-chain delay: do not pick up a release in its first days.
+    cooldown:
+      default-days: 3
+    groups:
+      dev-dependencies:
+        dependency-type: development
+        update-types: [minor, patch]
+
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: next
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 3
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,55 +2,81 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, next]
+  # Every pull request, including stacked ones whose base is another feature branch.
   pull_request:
   workflow_call:
 
+# Least privilege: jobs only read the repository.
+permissions:
+  contents: read
+
+# A new push to the same PR or branch cancels the run still in progress.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# Actions are pinned to full commit SHAs (tag in the comment); Dependabot keeps them current.
 jobs:
+  test:
+    name: Test (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Ruby lines still maintained upstream; 3.3 is the minimum in the gemspec.
+        ruby: ["3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Test
+        run: bundle exec rake test
+
+      - name: Build gem
+        run: gem build octaspace.gemspec --strict
+
   lint:
     name: Lint (StandardRB)
     runs-on: ubuntu-latest
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
-      - uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
         with:
-          ruby-version: "3.4"
+          ruby-version: "4.0"
           bundler-cache: true
 
       - name: StandardRB
         run: bundle exec standardrb
 
-  test:
-    name: Ruby ${{ matrix.ruby }} / ${{ matrix.gemfile }}
+  security:
+    name: Dependency audit
     runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    strategy:
-      fail-fast: false
-      matrix:
-        ruby:
-          - "3.2"
-          - "3.3"
-          - "3.4"
-        gemfile:
-          - gemfiles/rails_7_1.gemfile
-          - gemfiles/rails_7_2.gemfile
-          - gemfiles/rails_8_0.gemfile
-
-    env:
-      BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}
-      BUNDLE_PATH_RELATIVE_TO_CWD: true
+    timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
-      - uses: ruby/setup-ruby@v1
+      - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
         with:
-          ruby-version: ${{ matrix.ruby }}
+          ruby-version: "4.0"
           bundler-cache: true
 
-      - name: Test
-        run: bundle exec rake test
+      # Fails on any advisory for the resolved gems (fresh advisory database each run).
+      - name: bundler-audit
+        run: bundle exec bundle-audit check --update
diff --git a/Appraisals b/Appraisals
diff --git a/Gemfile b/Gemfile
@@ -5,16 +5,12 @@ source "https://rubygems.org"
 gemspec
 
 # Development & testing
-gem "minitest", "~> 5.0"
-gem "webmock", "~> 3.0"
-gem "standard", "~> 1.0"    # StandardRB linter
-gem "rake", "~> 13.0"
-gem "appraisal"
+gem "minitest", "~> 6.0"
+gem "webmock", "~> 3.34"
+gem "standard", "~> 1.57" # StandardRB linter
+gem "rake", "~> 13.3"
+gem "bundler-audit", "~> 0.9", require: false
 
 # Optional persistent mode (needed for persistent_transport tests)
-gem "faraday-net_http_persistent", "~> 2.1"
-gem "connection_pool", "~> 2.4"
-
-# Rails (for Railtie/Engine/dummy app tests)
-gem "railties", ">= 7.1"
-gem "puma", "~> 6.0"
+gem "faraday-net_http_persistent", "~> 2.3"
+gem "connection_pool", ">= 2.4", "< 4"
diff --git a/README.md b/README.md
@@ -15,8 +15,7 @@ Official Ruby SDK for the [OctaSpace API](https://api.octa.space/api-docs).
 - **Typed error hierarchy** — 12 exception classes mapped from HTTP status codes
 - **`on_request` / `on_response` hooks** — for logging, tracing, APM
 - **Rails integration** — Railtie, shared client, graceful shutdown at_exit
-- **Playground app** — `bin/playground` with live diagnostics page
-- **Ruby ≥ 3.2**, Rails 7.1 / 7.2 / 8.0
+- **Ruby ≥ 3.3**; optional Railtie for Rails apps
 
 ## Installation
 
@@ -258,25 +257,6 @@ node.id        # => 123
 
 Available types: `Node`, `Account`, `Balance`, `Session`.
 
-## Playground App
-
-Interactive demo for manual testing against a real API key:
-
-```bash
-OCTA_API_KEY=your_key bin/playground
-# → http://localhost:3000
-```
-
-Pages:
-
-| Route | Content |
-|---|---|
-| `/playground/account` | Profile + balance |
-| `/playground/nodes` | Node list with state badges |
-| `/playground/sessions` | Current + recent sessions, including live-format quirks |
-| `/playground/services` | Marketplace catalogs for MR, Render, and VPN |
-| `/playground/diagnostics` | Direct SDK method runner for contracts, payloads, transport mode, and pool stats |
-
 ## Development
 
 ### Gem Development
@@ -304,33 +284,6 @@ irb
 > client_auth.accounts.profile.data # Retrieving profile data (email, ID, etc.)
 ```
 
-### Running tests against multiple Rails versions
-
-```bash
-bundle exec appraisal rails-7-1 rake test
-bundle exec appraisal rails-7-2 rake test
-bundle exec appraisal rails-8-0 rake test
-```
-
-### Dummy Application (Playground)
-
-The repository includes a Rails "Dummy" application for manual testing and UI prototyping. It is located in `test/dummy`.
-
-To run the dummy app:
-
-1. Ensure you have an API key: `export OCTA_API_KEY=your_key`
-2. Run the playground script: `bin/playground` (starts Puma on port 3000)
-3. Visit `http://localhost:3000/playground/diagnostics`
-
-You can also run it manually from the directory:
-
-```bash
-cd test/dummy
-bin/rails server
-```
-
-The dummy app is configured to use the local version of the gem. It is **not** included in the published gem package.
-
 ## Packaging and Publishing
 
 See [PUBLISHING.md](PUBLISHING.md) for instructions on how to package and release new versions of the gem.

diff --git a/bin/playground b/bin/playground
diff --git a/docs/GIT_WORKFLOW_NEXT.md b/docs/GIT_WORKFLOW_NEXT.md
@@ -0,0 +1,106 @@
+# Working with the `next` branch
+
+`next` is the branch that moves the SDK to the new OctaSpace API (test stand `https://api-dev.octa.space`).
+All changes for the new API go to `next` as pull requests; merging `next → main` is a separate decision,
+made when the new API reaches production. `main` stays the branch of the current (legacy) SDK and its hotfixes.
+Cube, go-sdk, js-sdk and octa-cli work the same way.
+
+The default branch on GitHub is **`main`**. A PR opened without an explicit base therefore targets `main`,
+not `next`.
+
+## `main` and `next`, step by step
+
+| Step | Working with `main` | Working with `next` |
+|---|---|---|
+| Update branches | `git fetch origin` | `git fetch origin` (same) |
+| Switch to the base branch | `git switch main` | `git switch next` |
+| Pull the latest code | `git pull` | `git pull` (same; `next` tracks `origin/next`) |
+| New task branch | `git switch -c feat/x` (from `main`) | `git switch -c feat/x origin/next` ← **the key difference** |
+| Commit | `git add …` → `git commit` | same |
+| First push of the branch | `git push -u origin feat/x` | same (push the task branch, not `next`) |
+| Catch up with the base | `git rebase origin/main` | `git rebase origin/next` |
+| PR with `gh` | `gh pr create` | `gh pr create --base next` ← **required** |
+| PR on the website | base `main` is preselected | change **base: main → next** by hand |
+| Branch diff against the base | `git diff main...HEAD` | `git diff origin/next...HEAD` |
+| After the PR is merged | `git switch main && git pull` | `git switch next && git pull` |
+
+`git switch -c feat/x origin/next` creates the task branch straight from the remote `next`,
+even if you are on `main` and have no local `next`. The branch tracks `origin/next` at first;
+the first `git push -u origin feat/x` switches it to its own remote branch.
+
+## Typical task cycle
+
+```bash
+git fetch origin
+git switch -c feat/my-task origin/next   # from a fresh next, even when you are on main
+# ... changes ...
+bundle exec rake test && bundle exec standardrb
+git add -A && git commit -m "…"
+git push -u origin feat/my-task
+gh pr create --base next                 # without --base the PR opens against main
+```
+
+If something was merged into `next` while you were working, update the branch before the PR:
+
+```bash
+git fetch origin
+git rebase origin/next
+git push --force-with-lease              # a plain push is refused after a rebase
+```
+
+## Dependent PRs (a stack)
+
+When task B builds on task A that is not merged yet, create branch B from A and open the PR
+with base A: `gh pr create --base feat/a`. The PR then shows only B's changes.
+
+⚠️ **Do not delete branch A when merging it** (`gh pr merge --delete-branch` or the
+"Delete branch" button) while PR B points at it: GitHub **closes** PR B instead of retargeting it.
+Merge the stack one PR at a time, in this order:
+
+```bash
+gh pr merge <A> --merge                 # without --delete-branch
+gh pr edit <B> --base next              # retarget the next PR
+git push origin --delete feat/a         # now branch A can be deleted
+```
+
+If PR B was closed anyway: restore branch A at its last commit
+(`git push origin <sha>:refs/heads/feat/a`), then `gh pr reopen <B>` and
+`gh pr edit <B> --base next`.
+
+## Easy mistakes
+
+1. **The PR opened against `main`.** `--base next` was forgotten or the base was not changed on the
+   website, so the PR shows the whole difference between `next` and `main`.
+   Fix: `gh pr edit <N> --base next`.
+2. **The branch was created from `main`.** `git switch -c feat/x` while on `main` branches off `main`,
+   and a PR into `next` drags in extra commits. Always name the base explicitly (`origin/next`)
+   instead of relying on the current branch.
+   Fix: `git rebase --onto origin/next origin/main feat/x`.
+3. **Pushing straight to `next`.** Push only task branches; changes reach `next` through PRs,
+   just like `main`.
+4. **Hotfixes on `main` never reach `next`.** Urgent fixes to the legacy SDK go in a branch from
+   `main` with a PR into `main`. So that they are not lost, merge `main` into `next` from time to time
+   in a separate PR:
+
+   ```bash
+   git switch -c chore/sync-main-into-next origin/next
+   git merge origin/main
+   git push -u origin chore/sync-main-into-next
+   gh pr create --base next
+   ```
+
+5. **A stale local `next`.** It only moves on `git pull`. For new branches and rebases it is safer
+   to use `origin/next` right after `git fetch`.
+
+## CI and releases
+
+- CI (`.github/workflows/ci.yml`) runs on pushes to `main` and `next` and on every PR, stacked ones included.
+- Dependabot opens update PRs against `next` (`target-branch` in `.github/dependabot.yml`).
+  After `next` is merged into `main`, set `target-branch: main` again.
+- The gem is not published to RubyGems from `next` until the new API reaches production.
+
+## If `next` lives for a long time
+
+The default branch on GitHub (Settings → Branches) can be switched to `next`: PRs then target it
+by default and mistake 1 goes away. This changes the default base for the whole team, so it is a
+team decision, not one developer's.
diff --git a/gemfiles/rails_7_1.gemfile b/gemfiles/rails_7_1.gemfile