feat: add a doctor check for the owning team

Reports whether the project is attached to a team, and surfaces
`zitadel claim` in the advisory when it is not.

Always a warning, never a failure. An unattached project works exactly
like an attached one, same issuer, same users, same applications, so the
only thing missing is durability and that is the developer's call rather
than a defect. It matters mechanically too: `doctor` turns any `fail`
into a thrown `E_VALIDATION`, so failing here would break every scripted
`zitadel doctor` run against a project nobody had claimed yet.

Implements `SanityCheck` directly rather than extending the abstract
base, for the same reason `ManagedFilesCheck` does: the base's
verify-throws contract can only express pass or fail. That also means
nothing wraps a throw from `run`, so an unreadable secret or config is
caught and reported as a skip. Otherwise a missing `.zitadel/secret`
would crash the whole battery on a nudge and hide the `secret` check that
actually reports the problem, with its repair path.

`fix` stays the inherited no-op. `doctor --fix` calls it on every
non-passing check, but a claim needs a human to sign in through a
browser, so there is nothing safe to automate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: IAM-marco

apps/cli/src/commands/doctor/checks/claim.ts

@@ -0,0 +1,81 @@
+import { claimState, type ClaimState } from "../../../lib/claim-state";
+import { readProjectServer, readZitadelConfig, readZitadelSecret } from "../../../lib/project";
+import type { CheckContext, CheckOutcome, SanityCheck } from "./types";
+
+/**
+ * Reports whether the project is attached to a team, reading `claimed_at` and
+ * `team_id` from `.zitadel/secret`.
+ *
+ * Always advisory, never a failure. An unattached project works exactly like an
+ * attached one — same issuer, same users, same applications — so the only thing
+ * missing is durability, which is the developer's call and not a defect. That
+ * matters mechanically too: `doctor` turns any `fail` into a thrown
+ * `E_VALIDATION`, so failing here would break every scripted `zitadel doctor`
+ * against a project nobody had claimed yet.
+ *
+ * Implements {@link SanityCheck} directly rather than via the abstract base,
+ * for the same reason `ManagedFilesCheck` does: the base's `verify`-throws
+ * contract can only express pass/fail, and this check is only ever warn or
+ * pass.
+ */
+export class ClaimCheck implements SanityCheck {
+  readonly name = "claim";
+  readonly path = ".zitadel/secret";
+
+  async run(ctx: CheckContext): Promise<CheckOutcome> {
+    let state;
+    try {
+      state = claimState({
+        secret: await readZitadelSecret(ctx.cwd),
+        // From `zitadel.json`, not the command's own source: `doctor` pins its
+        // source to the local runtime URL, so asking it where the project lives
+        // would report every project as local.
+        server: readProjectServer(await readZitadelConfig(ctx.cwd)),
+      });
+    } catch {
+      // A missing or unparseable secret/config is already reported, loudly and
+      // with a repair path, by the `secret` and `config` checks. Implementing
+      // `SanityCheck` directly means nothing wraps a throw here, so swallowing
+      // it is what keeps a broken project reporting its real problem instead of
+      // crashing the whole battery on a nudge.
+      return {
+        name: this.name,
+        status: "pass",
+        message: "Skipped: could not read the project files that record the owning team",
+        path: this.path,
+      };
+    }
+
+    if (state.kind === "detached") {
+      return {
+        name: this.name,
+        status: "warn",
+        message:
+          "This project is temporary until you attach it to a team. Run `zitadel claim` " +
+          "to make it permanent; nothing about the project changes.",
+        path: this.path,
+      };
+    }
+
+    return {
+      name: this.name,
+      status: "pass",
+      message:
+        state.kind === "attached"
+          ? `Project is attached to team ${state.team_id}`
+          : // Local and self-hosted servers have no team to attach to, so the
+            // check passes rather than warning about an impossible action.
+            "Project is not on a server where teams apply",
+      path: this.path,
+    };
+  }
+
+  /**
+   * Deliberately a no-op. `doctor --fix` calls `fix` on every non-passing
+   * check, but claiming requires a human to sign in through a browser, so there
+   * is nothing safe to automate here.
+   */
+  async fix(_ctx: CheckContext): Promise<void> {
+    return;
+  }
+}

apps/cli/src/commands/doctor/checks/index.ts

@@ -15,6 +15,7 @@ import { DependencyCheck } from "./dependency";
 import { ManagedFilesCheck } from "./managed-files";
 import { ProjectMatchCheck } from "./project-match";
 import { SchemaCheck } from "./schema";
+import { ClaimCheck } from "./claim";
 
 export type { SanityCheck, CheckContext, CheckOutcome } from "./types";
 export { AbstractSanityCheck } from "./types";
@@ -28,6 +29,7 @@ export { SchemaCheck } from "./schema";
 export { DependencyCheck } from "./dependency";
 export { ManagedFilesCheck } from "./managed-files";
 export { ProjectMatchCheck } from "./project-match";
+export { ClaimCheck } from "./claim";
 
 /** Every diagnostic the `doctor` command runs, in display order. */
 export const SANITY_CHECKS: ReadonlyArray<SanityCheck> = [
@@ -41,4 +43,5 @@ export const SANITY_CHECKS: ReadonlyArray<SanityCheck> = [
   new DependencyCheck(),
   new ManagedFilesCheck(),
   new ProjectMatchCheck(),
+  new ClaimCheck(),
 ];

apps/cli/src/commands/doctor/index.ts

@@ -1,6 +1,7 @@
 import { Flags } from "@oclif/core";
 import consola from "consola";
 
+import { claimAction, claimCommand } from "../../lib/claim-state";
 import { ZitadelError } from "../../lib/errors";
 import { assertServerPackageAvailable } from "../../lib/local-server/binary";
 import { dockerAvailable, imageAvailable } from "../../lib/local-server/docker";
@@ -259,6 +260,11 @@ function advisoryForWarnings(
     nextCommands.push(...advice.nextCommands);
   }
 
+  if (warnings.some((check) => check.name === "claim")) {
+    nextActions.push(claimAction(cliVersion));
+    nextCommands.push(claimCommand(cliVersion));
+  }
+
   const managedRuntimeWarning = warnings.find((check) => check.name === "managed-runtime-processes");
   if (hasManagedRuntimeProcesses(managedRuntimeWarning)) {
     nextActions.push(

apps/cli/tests/unit/commands/doctor.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { MANAGED_MARKER } from "../../../src/lib/paths";
-import { parseJson, runCliForTest } from "../../helpers/run-cli";
+import { expectedPublicCliCommand, parseJson, runCliForTest } from "../../helpers/run-cli";
 
 type Check = { name: string; status: "pass" | "warn" | "fail"; message: string; path?: string };
 
@@ -46,7 +46,9 @@ async function doctor(cwd: string, extra: string[] = []) {
  * Builds a well-formed managed project that should pass every doctor check
  * runnable without the platform: config/secret parse + match, 0600 secret,
  * gitignore + env.example coverage, a Next.js framework signature, a valid
- * user schema, and a Zitadel SDK dependency.
+ * user schema, a Zitadel SDK dependency, and an owning team recorded by
+ * `zitadel claim` (without it the claim check warns, which is its own test
+ * below).
  */
 async function makeHealthyProject(): Promise<string> {
   const cwd = await mkdtemp(join(tmpdir(), "zitadel-doctor-"));
@@ -80,6 +82,8 @@ async function makeHealthyProject(): Promise<string> {
       preview_secret: "sk_proj_preview",
       preview_origins: [],
       created_at: "2026-01-01T00:00:00.000Z",
+      claimed_at: "2026-01-02T00:00:00.000Z",
+      team_id: "team-001",
     }),
   );
   await chmod(join(cwd, ".zitadel/secret"), 0o600);
@@ -112,6 +116,24 @@ async function makeHealthyProject(): Promise<string> {
   return cwd;
 }
 
+/**
+ * Rewrites the secret without `claimed_at`/`team_id`, i.e. a project that has
+ * been set up but never claimed — the state every project starts in.
+ */
+async function writeDetachedSecret(cwd: string): Promise<void> {
+  await writeFile(
+    join(cwd, ".zitadel/secret"),
+    JSON.stringify({
+      project_id: "proj-001",
+      project_secret: "sk_proj_test",
+      preview_secret: "sk_proj_preview",
+      preview_origins: [],
+      created_at: "2026-01-01T00:00:00.000Z",
+    }),
+  );
+  await chmod(join(cwd, ".zitadel/secret"), 0o600);
+}
+
 afterEach(async () => {
   for (const server of servers.splice(0)) {
     await new Promise<void>((resolve) => server.close(() => resolve()));
@@ -143,11 +165,74 @@ describe("doctor command", () => {
     expect(names).toContain("secret");
     expect(names).toContain("dependency");
     expect(names).toContain("project-match");
+    expect(names).toContain("claim");
     expect(names).not.toContain("managed-login");
     expect(names).not.toContain("managed-register");
     expect(names).not.toContain("managed-middleware");
   });
 
+  // The nudge has to stay advisory: doctor throws E_VALIDATION on any `fail`,
+  // so failing here would break every scripted `zitadel doctor` run against a
+  // project nobody has attached to a team yet.
+  it("warns (but passes) when the project is not attached to a team, and points at claim", async () => {
+    const cwd = await makeHealthyProject();
+    await writeDetachedSecret(cwd);
+
+    const res = await doctor(cwd);
+
+    expect(res.exitCode).toBe(0);
+    const json = parseJson(res.stdout) as {
+      status: string;
+      data: { ok: boolean; checks: Check[]; next_commands?: string[] };
+    };
+    expect(json.status).toBe("ok");
+    expect(json.data.ok).toBe(true);
+    const claim = json.data.checks.find((check) => check.name === "claim");
+    expect(claim?.status).toBe("warn");
+    expect(claim?.message).toContain("temporary until you attach it to a team");
+    expect(json.data.next_commands).toContain(expectedPublicCliCommand("claim"));
+  });
+
+  // Claiming needs a human in a browser, so --fix has nothing safe to do. The
+  // warning has to survive it rather than being silently "repaired".
+  it("leaves the claim warning (and the secret) alone under --fix", async () => {
+    const cwd = await makeHealthyProject();
+    await writeDetachedSecret(cwd);
+    const before = await readFile(join(cwd, ".zitadel/secret"), "utf8");
+
+    const res = await doctor(cwd, ["--fix"]);
+
+    expect(res.exitCode).toBe(0);
+    const json = parseJson(res.stdout) as { data: { ok: boolean; checks: Check[] } };
+    expect(json.data.checks.find((check) => check.name === "claim")?.status).toBe("warn");
+    expect(await readFile(join(cwd, ".zitadel/secret"), "utf8")).toBe(before);
+  });
+
+  // A local project has no platform team to attach to, so the nudge must not
+  // follow `zitadel setup --server local` around forever.
+  it("passes the claim check without a nudge for a local project", async () => {
+    const cwd = await makeHealthyProject();
+    await writeDetachedSecret(cwd);
+    await writeFile(
+      join(cwd, "zitadel.json"),
+      JSON.stringify({
+        project: "proj-001",
+        server: "http://localhost:8080",
+        framework: { id: "next" },
+        environments: { development: { issuer: "http://localhost:3000" } },
+      }),
+    );
+
+    const res = await doctor(cwd);
+
+    expect(res.exitCode).toBe(0);
+    const json = parseJson(res.stdout) as {
+      data: { checks: Check[]; next_commands?: string[] };
+    };
+    expect(json.data.checks.find((check) => check.name === "claim")?.status).toBe("pass");
+    expect(json.data.next_commands ?? []).not.toContain(expectedPublicCliCommand("claim"));
+  });
+
   it("warns (but passes) when .zitadel/schemas is empty — legacy or interrupted projects", async () => {
     const cwd = await makeHealthyProject();
     await rm(join(cwd, ".zitadel/schemas/user.json"));

apps/cli/tests/unit/commands/doctor/checks.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 
 import {
+  ClaimCheck,
   ConfigCheck,
   DependencyCheck,
   EnvExampleCheck,
@@ -941,6 +942,71 @@ describe("ProjectMatchCheck", () => {
   });
 });
 
+describe("ClaimCheck", () => {
+  /** Rewrites `.zitadel/secret`, preserving the 0600 mode doctor asserts elsewhere. */
+  async function writeSecret(cwd: string, extra: Record<string, unknown>): Promise<void> {
+    await writeFile(join(cwd, ".zitadel/secret"), JSON.stringify({ ...SECRET, ...extra }));
+    await chmod(join(cwd, ".zitadel/secret"), 0o600);
+  }
+
+  /** Rewrites `zitadel.json` with a different `server`, leaving everything else intact. */
+  async function writeServer(cwd: string, server: string): Promise<void> {
+    const config = JSON.parse(await readFile(join(cwd, "zitadel.json"), "utf8")) as Record<
+      string,
+      unknown
+    >;
+    await writeFile(join(cwd, "zitadel.json"), JSON.stringify({ ...config, server }));
+  }
+
+  it("warns for a cloud project with no owning team", async () => {
+    const cwd = await makeProject();
+    const outcome = await new ClaimCheck().run(ctxFor(cwd));
+    expect(outcome.status).toBe("warn");
+    expect(outcome.message).toContain("temporary until you attach it to a team");
+  });
+
+  it("passes and names the team once attached", async () => {
+    const cwd = await makeProject();
+    await writeSecret(cwd, { claimed_at: "2026-01-02T00:00:00.000Z", team_id: "team-001" });
+    const outcome = await new ClaimCheck().run(ctxFor(cwd));
+    expect(outcome.status).toBe("pass");
+    expect(outcome.message).toContain("team-001");
+  });
+
+  // Local and self-hosted servers have no platform team, so there is nothing to
+  // nudge toward and a warning would be permanent noise.
+  it("passes without a nudge off the cloud", async () => {
+    for (const server of ["http://localhost:8080", "https://zitadel.example.com"]) {
+      const cwd = await makeProject();
+      await writeServer(cwd, server);
+      const outcome = await new ClaimCheck().run(ctxFor(cwd));
+      expect(outcome.status).toBe("pass");
+      expect(outcome.message).not.toContain("temporary");
+    }
+  });
+
+  // Nothing wraps a throw from this check (it implements SanityCheck directly),
+  // so an unreadable secret must not take the whole battery down with it — the
+  // `secret` check is the one that reports that problem.
+  it("skips instead of throwing when the secret cannot be read", async () => {
+    const cwd = await makeProject();
+    await rm(join(cwd, ".zitadel/secret"));
+    const outcome = await new ClaimCheck().run(ctxFor(cwd));
+    expect(outcome.status).toBe("pass");
+    expect(outcome.message).toContain("Skipped");
+  });
+
+  // `doctor --fix` calls fix() on every non-passing check. Claiming needs a
+  // browser, so this one must be inert rather than half-writing the record.
+  it("has no automatic repair", async () => {
+    const cwd = await makeProject();
+    const before = await readFile(join(cwd, ".zitadel/secret"), "utf8");
+    await new ClaimCheck().fix(ctxFor(cwd));
+    expect(await readFile(join(cwd, ".zitadel/secret"), "utf8")).toBe(before);
+    expect((await new ClaimCheck().run(ctxFor(cwd))).status).toBe("warn");
+  });
+});
+
 describe("loadPatchContext", () => {
   it("reconstructs the patch context from on-disk project files", async () => {
     const cwd = await makeProject();