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

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">