docs: update all documentation for subscription auth, billing tiers, and API key management

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-Claude)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

.gitea/workflows/publish-npm.yml

@@ -0,0 +1,40 @@
+name: Publish npm packages
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        run: |
+          echo "VERSION=$(echo $GITHUB_REF_NAME | sed 's/^v//')" >> $GITHUB_ENV
+
+      - name: Configure npm auth
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+
+      - name: Update package versions
+        run: |
+          cd packages/sdk-ts && npm version $VERSION --no-git-tag-version
+          cd ../opencode-plugin && npm version $VERSION --no-git-tag-version
+
+      - name: Publish agentlens-sdk
+        run: |
+          cd packages/sdk-ts
+          npm install
+          npm run build
+          npm publish --access public
+
+      - name: Publish opencode-agentlens
+        run: |
+          cd packages/opencode-plugin
+          npm install
+          npm run build
+          npm publish --access public

.gitea/workflows/publish-pypi.yml

@@ -0,0 +1,32 @@
+name: Publish PyPI package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      TWINE_USERNAME: __token__
+      TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        run: |
+          echo "VERSION=$(echo $GITHUB_REF_NAME | sed 's/^v//')" >> $GITHUB_ENV
+
+      - name: Update version in pyproject.toml
+        run: |
+          cd packages/sdk-python
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+
+      - name: Build and publish to PyPI
+        run: |
+          cd packages/sdk-python
+          pip install build twine
+          python -m build
+          twine upload dist/*

README.md

@@ -18,6 +18,15 @@
 
 Existing observability tools show you _what_ LLM calls were made. AgentLens shows you _why_ your agent made each decision along the way -- which tool it picked, what alternatives it rejected, and the reasoning behind every choice.
 
+## Getting Started
+
+1. **Register** at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) with your email and password.
+2. **Log in** to the dashboard at [agentlens.vectry.tech](https://agentlens.vectry.tech).
+3. **Create an API key** in **Settings > API Keys**.
+4. **Install the SDK** and start tracing.
+
+> Self-hosting? You do not need to register with the hosted service. See [Self-Hosting](#self-hosting) below.
+
 ## Quick Start
 
 ```bash
@@ -27,6 +36,7 @@ pip install vectry-agentlens
 ```python
 import agentlens
 
+# Use the API key you created in Settings > API Keys
 agentlens.init(api_key="your-key", endpoint="https://agentlens.vectry.tech")
 
 with agentlens.trace("my-agent-task", tags=["production"]):
@@ -41,7 +51,7 @@ with agentlens.trace("my-agent-task", tags=["production"]):
 agentlens.shutdown()
 ```
 
-Open `https://agentlens.vectry.tech/dashboard` to see your traces.
+Open `https://agentlens.vectry.tech/dashboard` to see your traces (login required).
 
 ## Features
 
@@ -72,7 +82,7 @@ Add to your `opencode.json`:
 }
 ```
 
-Set environment variables:
+Set environment variables (use the API key from your dashboard at **Settings > API Keys**):
 
 ```bash
 export AGENTLENS_API_KEY="your-key"
@@ -90,6 +100,7 @@ npm install agentlens-sdk
 ```typescript
 import { init, TraceBuilder, SpanType, SpanStatus } from "agentlens-sdk";
 
+// Use the API key from Settings > API Keys in your dashboard
 init({ apiKey: "your-key", endpoint: "https://agentlens.vectry.tech" });
 
 const trace = new TraceBuilder("my-agent-task", {
@@ -173,8 +184,24 @@ with agentlens.trace("planner"):
 | `MEMORY_RETRIEVAL` | Agent chose what context to retrieve |
 | `CUSTOM` | Any other decision type |
 
+## Pricing
+
+AgentLens cloud ([agentlens.vectry.tech](https://agentlens.vectry.tech)) offers three billing tiers. One trace equals one session for billing purposes.
+
+| Plan | Price | Sessions | Details |
+|------|-------|----------|---------|
+| **Free** | $0 | 20 sessions/day | No credit card required |
+| **Starter** | $5/month | 1,000 sessions/month | For individual developers |
+| **Pro** | $20/month | 100,000 sessions/month | For teams and production workloads |
+
+Manage your subscription in **Settings > Billing** in the dashboard.
+
+Self-hosted instances are not subject to these limits.
+
 ## Self-Hosting
 
+Self-hosted AgentLens instances do not require registration with the hosted SaaS service. You manage your own API keys and have no session limits.
+
 ```bash
 git clone https://gitea.repi.fun/repi/agentlens.git
 cd agentlens

apps/web/src/app/docs/api-reference/page.tsx

@@ -55,9 +55,37 @@ export default function ApiReferencePage() {
       <section className="mb-6">
         <h2 className="text-2xl font-semibold mb-4">Authentication</h2>
         <p className="text-neutral-400 leading-relaxed mb-4">
-          All write endpoints require a Bearer token in the Authorization header:
+          All API endpoints require a Bearer token in the Authorization header.
+          To obtain an API key, register at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          , log in, and create a key in{" "}
+          <strong className="text-neutral-200">Settings &rarr; API Keys</strong>
+          .
         </p>
         <CodeBlock>{`Authorization: Bearer your-api-key`}</CodeBlock>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50 mt-4">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Rate limits:</strong>{" "}
+            API usage is governed by your billing tier. The Free plan allows 20
+            sessions per day. Starter ($5/month) allows 1,000 sessions per
+            month. Pro ($20/month) allows 100,000 sessions per month. One trace
+            equals one session for billing purposes. Manage your plan in{" "}
+            <strong className="text-neutral-300">Settings &rarr; Billing</strong>
+            . See{" "}
+            <a
+              href="/docs/authentication-billing"
+              className="text-emerald-400 hover:underline"
+            >
+              Authentication &amp; Billing
+            </a>{" "}
+            for details.
+          </p>
+        </div>
       </section>
 
       <hr className="border-neutral-800/50 my-10" />

apps/web/src/app/docs/authentication-billing/page.tsx

@@ -0,0 +1,200 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Authentication & Billing",
+  description:
+    "Register for AgentLens, manage API keys, and understand billing tiers and session limits.",
+};
+
+export default function AuthenticationBillingPage() {
+  return (
+    <div>
+      <h1 className="text-4xl font-bold tracking-tight mb-4">
+        Authentication &amp; Billing
+      </h1>
+      <p className="text-lg text-neutral-400 mb-10 leading-relaxed">
+        AgentLens cloud requires an account to access the dashboard and ingest
+        traces. This page covers registration, API key management, billing
+        tiers, and session counting.
+      </p>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Registration</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          To use AgentLens cloud, create an account at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          . You will need to provide an email address and password. Once
+          registered, log in at{" "}
+          <a
+            href="https://agentlens.vectry.tech"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech
+          </a>{" "}
+          to access the dashboard.
+        </p>
+        <p className="text-neutral-400 leading-relaxed">
+          The dashboard requires authentication -- there is no anonymous access.
+          All features including trace viewing, analytics, and settings are
+          available only after login.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">API keys</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          API keys authenticate your SDKs and integrations when sending traces
+          to AgentLens. Keys are generated per-user in the dashboard.
+        </p>
+        <h3 className="text-lg font-medium text-neutral-200 mb-2">
+          Creating an API key
+        </h3>
+        <ol className="list-decimal list-inside text-neutral-400 space-y-2 ml-1 mb-4">
+          <li>Log in to the AgentLens dashboard.</li>
+          <li>
+            Navigate to{" "}
+            <strong className="text-neutral-200">
+              Settings &rarr; API Keys
+            </strong>
+            .
+          </li>
+          <li>
+            Click <strong className="text-neutral-200">Create API Key</strong>,
+            give it a name, and copy the generated key.
+          </li>
+          <li>
+            Store the key securely. It will not be shown again after you leave
+            the page.
+          </li>
+        </ol>
+        <h3 className="text-lg font-medium text-neutral-200 mb-2">
+          Using your API key
+        </h3>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Pass the key to the SDK during initialization, or set it as the{" "}
+          <code className="text-emerald-400 font-mono text-xs bg-emerald-500/5 px-1.5 py-0.5 rounded">
+            AGENTLENS_API_KEY
+          </code>{" "}
+          environment variable. The SDKs will pick it up automatically.
+        </p>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Security note:</strong>{" "}
+            Treat API keys like passwords. Do not commit them to version control.
+            Use environment variables or a secrets manager in production.
+          </p>
+        </div>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Billing tiers</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          AgentLens cloud offers three billing tiers. One trace equals one
+          session for billing purposes.
+        </p>
+        <div className="overflow-x-auto mb-6">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-neutral-800">
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Plan
+                </th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Price
+                </th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">
+                  Sessions
+                </th>
+                <th className="text-left py-2 text-neutral-400 font-medium">
+                  Details
+                </th>
+              </tr>
+            </thead>
+            <tbody className="text-neutral-300">
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4 font-medium">Free</td>
+                <td className="py-2 pr-4">$0</td>
+                <td className="py-2 pr-4">20 sessions/day</td>
+                <td className="py-2">
+                  No credit card required. Ideal for experimentation and
+                  personal projects.
+                </td>
+              </tr>
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4 font-medium">Starter</td>
+                <td className="py-2 pr-4">$5/month</td>
+                <td className="py-2 pr-4">1,000 sessions/month</td>
+                <td className="py-2">
+                  For individual developers with moderate tracing needs.
+                </td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-4 font-medium">Pro</td>
+                <td className="py-2 pr-4">$20/month</td>
+                <td className="py-2 pr-4">100,000 sessions/month</td>
+                <td className="py-2">
+                  For teams and production workloads with high trace volume.
+                </td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Session counting</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          A session is equivalent to a single trace sent to the AgentLens API.
+          Each call to{" "}
+          <code className="text-emerald-400 font-mono text-xs bg-emerald-500/5 px-1.5 py-0.5 rounded">
+            POST /api/traces
+          </code>{" "}
+          that includes one trace counts as one session, regardless of how many
+          spans, decision points, or events are inside that trace.
+        </p>
+        <p className="text-neutral-400 leading-relaxed">
+          If you batch multiple traces in a single API call, each trace in the
+          batch counts as a separate session.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Managing your subscription
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          To view your current plan, upgrade, downgrade, or manage payment
+          methods, go to{" "}
+          <strong className="text-neutral-200">
+            Settings &rarr; Billing
+          </strong>{" "}
+          in the dashboard. Changes take effect immediately. If you downgrade
+          mid-cycle, you retain access to the higher tier until the end of the
+          current billing period.
+        </p>
+      </section>
+
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">Self-hosted instances</h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          If you are running a self-hosted AgentLens instance, registration with
+          the hosted SaaS service is not required. Self-hosted deployments
+          manage their own authentication and have no session limits or billing
+          tiers. See the{" "}
+          <a
+            href="/docs/self-hosting"
+            className="text-emerald-400 hover:underline"
+          >
+            Self-Hosting guide
+          </a>{" "}
+          for setup instructions.
+        </p>
+      </section>
+    </div>
+  );
+}

apps/web/src/app/docs/getting-started/page.tsx

@@ -63,6 +63,39 @@ export default function GettingStartedPage() {
         </ul>
       </section>
 
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Step 0: Create your account
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Before you can send traces, you need an AgentLens account. Register
+          with your email and password at{" "}
+          <a
+            href="https://agentlens.vectry.tech/register"
+            className="text-emerald-400 hover:underline"
+          >
+            agentlens.vectry.tech/register
+          </a>
+          . Once registered, log in to the dashboard and navigate to{" "}
+          <strong className="text-neutral-200">Settings &rarr; API Keys</strong>{" "}
+          to generate your first API key.
+        </p>
+        <div className="px-4 py-3 rounded-lg bg-neutral-900/50 border border-neutral-800/50 mb-4">
+          <p className="text-sm text-neutral-400">
+            <strong className="text-neutral-300">Self-hosting?</strong>{" "}
+            If you are running your own AgentLens instance, you do not need to
+            register with the hosted service. See the{" "}
+            <a
+              href="/docs/self-hosting"
+              className="text-emerald-400 hover:underline"
+            >
+              Self-Hosting guide
+            </a>{" "}
+            instead.
+          </p>
+        </div>
+      </section>
+
       <section className="mb-12">
         <h2 className="text-2xl font-semibold mb-4">
           Step 1: Install the SDK
@@ -194,6 +227,57 @@ await trace.end();`}</CodeBlock>
         </a>
       </section>
 
+      <section className="mb-12">
+        <h2 className="text-2xl font-semibold mb-4">
+          Billing and session limits
+        </h2>
+        <p className="text-neutral-400 leading-relaxed mb-4">
+          Each trace you send counts as one session for billing purposes.
+          AgentLens cloud offers three tiers:
+        </p>
+        <div className="overflow-x-auto mb-4">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-neutral-800">
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">Plan</th>
+                <th className="text-left py-2 pr-4 text-neutral-400 font-medium">Price</th>
+                <th className="text-left py-2 text-neutral-400 font-medium">Sessions</th>
+              </tr>
+            </thead>
+            <tbody className="text-neutral-300">
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4">Free</td>
+                <td className="py-2 pr-4">$0</td>
+                <td className="py-2">20 sessions/day</td>
+              </tr>
+              <tr className="border-b border-neutral-800/50">
+                <td className="py-2 pr-4">Starter</td>
+                <td className="py-2 pr-4">$5/month</td>
+                <td className="py-2">1,000 sessions/month</td>
+              </tr>
+              <tr>
+                <td className="py-2 pr-4">Pro</td>
+                <td className="py-2 pr-4">$20/month</td>
+                <td className="py-2">100,000 sessions/month</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-neutral-400 leading-relaxed">
+          Manage your subscription in{" "}
+          <strong className="text-neutral-200">Settings &rarr; Billing</strong>{" "}
+          in the dashboard. Self-hosted instances are not subject to these
+          limits. See{" "}
+          <a
+            href="/docs/authentication-billing"
+            className="text-emerald-400 hover:underline"
+          >
+            Authentication &amp; Billing
+          </a>{" "}
+          for full details.
+        </p>
+      </section>
+
       <section className="mb-12">
         <h2 className="text-2xl font-semibold mb-4">Next steps</h2>
         <div className="grid sm:grid-cols-2 gap-4">

apps/web/src/app/docs/page.tsx

@@ -22,6 +22,12 @@ const sections = [
         description:
           "Understand Traces, Spans, Decision Points, and Events — the four building blocks of AgentLens.",
       },
+      {
+        title: "Authentication & Billing",
+        href: "/docs/authentication-billing",
+        description:
+          "Register for an account, manage API keys, and understand billing tiers and session limits.",
+      },
     ],
   },
   {

apps/web/src/app/docs/self-hosting/page.tsx

@@ -14,6 +14,9 @@ export default function SelfHostingPage() {
       <p className="text-lg text-neutral-400 mb-10 leading-relaxed">
         AgentLens is open source and designed to be self-hosted. You can deploy
         it with Docker in minutes, or run from source for development.
+        Self-hosted instances do not require registration with the AgentLens
+        cloud service and are not subject to any session limits or billing
+        tiers.
       </p>
 
       <section className="mb-12">

packages/opencode-plugin/README.md

@@ -8,6 +8,8 @@ OpenCode plugin for AgentLens — trace your coding agent's decisions, tool call
 ## Requirements
 
 - OpenCode >= 1.1.0
+- An AgentLens account -- register at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register)
+- An API key created in **Settings > API Keys** in the AgentLens dashboard
 
 ## Install
 
@@ -44,7 +46,7 @@ Add the plugin to your OpenCode configuration at `~/.config/opencode/opencode.js
 }
 ```
 
-Set your API key:
+Set your API key (create one at **Settings > API Keys** in the [AgentLens dashboard](https://agentlens.vectry.tech)):
 
 ```bash
 export AGENTLENS_API_KEY="your-api-key"
@@ -52,6 +54,8 @@ export AGENTLENS_API_KEY="your-api-key"
 
 The plugin activates automatically when OpenCode starts. No code changes required.
 
+Each OpenCode session counts as one trace (one session) for billing purposes. See the [billing documentation](https://agentlens.vectry.tech/docs/authentication-billing) for plan details.
+
 ## What Gets Captured
 
 The plugin hooks into OpenCode's event system and records:

packages/sdk-python/README.md

@@ -12,6 +12,8 @@ AgentLens is an observability SDK for AI agents. Unlike generic LLM tracing tool
 
 ## Quick Start
 
+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
 ```bash
 pip install vectry-agentlens
 ```
@@ -19,7 +21,7 @@ pip install vectry-agentlens
 ```python
 import agentlens
 
-# Initialize once at startup
+# Initialize with the API key from Settings > API Keys
 agentlens.init(api_key="your-api-key")
 
 # Trace any function with a decorator
@@ -160,7 +162,7 @@ Initialize the SDK. Call once at application startup.
 
 ```python
 agentlens.init(
-    api_key="your-api-key",           # Required. Your AgentLens API key.
+    api_key="your-api-key",           # Required. Create at Settings > API Keys in the dashboard.
     endpoint="https://...",            # API endpoint (default: https://agentlens.vectry.tech)
     flush_interval=5.0,               # Seconds between batch flushes (default: 5.0)
     max_batch_size=10,                 # Traces per batch before auto-flush (default: 10)
@@ -168,6 +170,8 @@ agentlens.init(
 )
 ```
 
+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
 ### `agentlens.trace()`
 
 Decorator or context manager that creates a trace (or a nested span if already inside a trace).
@@ -264,13 +268,25 @@ The SDK is lightweight and non-blocking. Traces are serialized and batched in a
 
 ## Dashboard
 
-View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech):
+View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech) (login required):
 
 - **Decision Trees** - Visualize the full decision path of every agent run
 - **Analytics** - Token usage, cost breakdowns, latency percentiles
 - **Real-time Streaming** - Watch agent decisions as they happen
 - **Session Grouping** - Track multi-turn conversations by session ID
 
+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
 ## Development
 
 ```bash

packages/sdk-ts/README.md

@@ -13,10 +13,12 @@ npm install agentlens-sdk
 
 ## Quick Start
 
+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
 ```typescript
 import { init, TraceBuilder, shutdown } from "agentlens-sdk";
 
-// Initialize the SDK
+// Initialize with the API key from Settings > API Keys
 init({
   apiKey: "your-api-key",
   endpoint: "https://agentlens.vectry.tech/api",
@@ -104,17 +106,31 @@ Pass `InitOptions` to `init()`:
 
 ```typescript
 init({
-  apiKey: "your-api-key",       // Required. Your AgentLens API key.
+  apiKey: "your-api-key",       // Required. Create at Settings > API Keys in the dashboard.
   endpoint: "https://...",      // API endpoint. Defaults to AgentLens cloud.
   maxBatchSize: 100,            // Max items per batch before auto-flush.
   flushInterval: 5000,          // Auto-flush interval in milliseconds.
 });
 ```
 
+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
 ## Transport
 
 The SDK ships with `BatchTransport`, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by `init()` — you typically do not need to instantiate it directly.
 
+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
 ## Documentation
 
 Full documentation: [agentlens.vectry.tech/docs/typescript-sdk](https://agentlens.vectry.tech/docs/typescript-sdk)