diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..dc281f8
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Require a changeset
+        run: |
+          if [ -z "$(ls -A .changeset/*.md 2>/dev/null | grep -v README)" ]; then
+            echo "No changeset found. Run 'npx changeset' and commit the result so this change gets a version bump."
+            exit 1
+          fi
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4e9d577..54dc145 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,12 +5,22 @@ on:
     branches:
       - main
 
+# Requires two repo secrets:
+#   NPM_REGISTRY_URL - full URL of the Verdaccio registry, reachable FROM THE RUNNER.
+#                      Not set yet: the registry currently listens on 127.0.0.1:4873 on
+#                      the dev server and the firewall allows only 80/443/SSH, so no
+#                      external runner can reach it. Until that is resolved this job
+#                      will fail at the publish step by design, rather than silently
+#                      skipping the release. See docs/PACKAGE-EXTRACTION.md in the
+#                      marketplaces repo.
+#   NPM_TOKEN        - publish token for that registry (npm login --registry=<url>).
+
 jobs:
   release:
     runs-on: ubuntu-latest
     permissions:
       contents: write
-      id-token: write
+      pull-requests: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -22,7 +32,6 @@ jobs:
         with:
           node-version: 20
           cache: npm
-          registry-url: https://registry.npmjs.org
 
       - name: Install dependencies
         run: npm ci
@@ -33,6 +42,21 @@ jobs:
       - name: Test
         run: npm test
 
+      - name: Configure registry auth
+        run: |
+          if [ -z "${{ secrets.NPM_REGISTRY_URL }}" ] || [ -z "${{ secrets.NPM_TOKEN }}" ]; then
+            echo "NPM_REGISTRY_URL and/or NPM_TOKEN are not set on this repo."
+            echo "The registry is not reachable from CI yet - see the comment at the top of this file."
+            exit 1
+          fi
+          REGISTRY="${{ secrets.NPM_REGISTRY_URL }}"
+          HOST_PATH="${REGISTRY#http://}"
+          HOST_PATH="${HOST_PATH#https://}"
+          {
+            echo "@marketplaces:registry=${REGISTRY}"
+            echo "//${HOST_PATH%/}/:_authToken=${{ secrets.NPM_TOKEN }}"
+          } >> .npmrc
+
       - name: Create release PR or publish
         uses: changesets/action@v1
         with:
@@ -40,4 +64,3 @@ jobs:
           publish: npm run release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
index f98b6c6..232118b 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,53 @@
 # vitanovaPackages
 
-Shared `@marketplaces/auth` and `@marketplaces/payment` client packages, consumed by `marketplaces` and other projects as npm dependencies. Extracted per ADR-0001 (see the `marketplaces` repo: `docs/context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md`).
+Shared client packages consumed by `marketplaces` and other projects as npm dependencies.
+
+- `packages/auth` — `@marketplaces/auth`. Real implementation. Two independent mechanisms: `telegram/` (live QR/session auth for customer + admin) and `ed25519/` (challenge/response admin auth, backend not shipped yet).
+- `packages/payment` — `@marketplaces/payment`. Scaffold only, no implementation yet.
+
+Full consumer documentation lives in the `marketplaces` repo: `docs/PACKAGES-USAGE.md`. Rationale: `docs/context/adrs/ADR-0001-extract-auth-and-payment-into-shared-marketplaces-packages.md`.
 
 ## Layout
 
-npm workspaces monorepo:
-- `packages/auth` — customer + admin auth client
-- `packages/payment` — payment/finance client (thin — business logic stays backend)
+npm workspaces monorepo. Each package builds standalone with `tsc` to `dist/`, which is the only thing published (`files: ["dist"]`).
 
-## Versioning & release
+```bash
+npm ci
+npm run build     # builds all workspaces
+npm test          # runs all workspace tests
+```
 
-[Changesets](https://github.com/changesets/changesets): `npm run changeset` to record an intended bump per PR, `.github/workflows/release.yml` opens a version PR on push to `main` and publishes on merge.
+Angular and rxjs are `peerDependencies` — the consuming app supplies them, so there is exactly one copy of Angular at runtime.
 
-`.github/workflows/release.yml` is written as GitHub Actions — if this host runs Gitea/Forgejo Actions the syntax is compatible; for Drone/Woodpecker or another CI it needs translating (same three steps: install, build+test, `changesets/action` equivalent).
+## Making a change
 
-Needs repo secrets: `NPM_TOKEN` (publish), `GITHUB_TOKEN` (provided by GH Actions; on Gitea use the built-in token equivalent).
+1. Edit under `packages/<name>/src`, export from `index.ts`.
+2. `npx changeset` — pick the package and bump type, write one line. CI rejects PRs without one.
+3. Open a PR. `ci.yml` builds, tests, and checks for the changeset.
+4. On merge to `main`, `release.yml` opens a "Version Packages" PR. Merging *that* publishes.
 
-## Status
+## Registry — read this before expecting CI to publish
 
-Scaffold only — no auth/payment implementation code has migrated in yet. Source is still live in the `marketplaces` repo (`src/app/core/auth`, `core/admin-auth`, `core/finance`, `core/pricing`) pending migration.
+Packages go to a **private Verdaccio registry running on the dev server** (`213.21.246.138`, Docker container `verdaccio`, storage `/srv/marketplaces/verdaccio/`), not npmjs.
+
+It currently listens on `127.0.0.1:4873` and the server firewall allows only 80/443/SSH — **so no CI runner can reach it.** `release.yml` fails loudly at the auth step rather than pretending to succeed. Resolving this needs one of:
+
+- a reverse proxy through the existing nginx (a server-config change, plus TLS — there is no certificate on that box yet), or
+- opening the port (plain HTTP with credentials on it — not recommended), or
+- moving to a hosted registry entirely.
+
+Until then, publish manually through an SSH tunnel:
+
+```bash
+ssh -L 4873:127.0.0.1:4873 seto@213.21.246.138
+```
+
+```bash
+npm login --registry=http://127.0.0.1:4873/ --scope=@marketplaces
+npm run build
+cd packages/auth && npm publish --registry http://127.0.0.1:4873/
+```
+
+Once reachable, set repo secrets `NPM_REGISTRY_URL` and `NPM_TOKEN` and CI takes over.
+
+`release.yml`/`ci.yml` use GitHub Actions syntax. Gitea/Forgejo Actions are compatible; other CI systems need translating (same steps: install, build, test, changesets).