@dotlabshq/clave 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @dotlabshq/clave
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect a repository to [clave](https://clave.one), the plan and work tracker for people and AI agents, in one command.
+
+```bash
+npx @dotlabshq/clave init
+```
+
+It runs in your terminal, in the repository, the first time you set it up on this machine:
+
+1. **Signs you in** through the browser (no token to copy). The sign-in lasts for this run only and is not saved.
+2. **Picks the org** and **the project**: it matches this repository's git remote. A missing project or unit is created when you are owner or admin; otherwise it tells you what an owner should run.
+3. **Picks the unit** (team) your agents work for.
+4. **Registers your agents** (default `coder`). An agent belongs to you: its id is `name@your-handle` (e.g. `coder@ayse`), so the same name can exist for other people. One token per agent.
+5. **Writes the MCP config by variable name**: `claude mcp add --scope local` with `Authorization: Bearer ${CLAVE_TOKEN_<AGENT>}` (stored on this machine, not in the repository); without the `claude` CLI it writes `.mcp.json`. The tokens themselves go to a git-ignored `.env.clave` (0600). Load it before starting your client: `set -a; . ./.env.clave; set +a`, or export those variables in your shell profile.
+6. **Adds a clave block** to `AGENTS.md` or `CLAUDE.md` (it asks first), so every agent session starts with `session_start`.
+
+Tokens are never printed and never written into a config file, so they never reach the chat or your AI agent's context.
+
+`init` refuses to run twice: when the repository already has the clave block or `clave-*` MCP servers it says so and points to `add`.
+
+## Adding to an existing setup
+
+Setup grows with the work; nothing has to be decided up front.
+
+```bash
+npx @dotlabshq/clave add unit <name>        # a new team in the plan (owner or admin)
+npx @dotlabshq/clave add project <name>     # a new project; repo = this folder's git remote (owner or admin)
+npx @dotlabshq/clave add agent <name>       # another agent of your own: token, MCP entry, AGENTS.md block
+```
+
+`add unit` and `add project` are the coordinator's, run with a person's token and the operator's approval; `add agent` is yours. After adding a server, open a **new** session: a running session does not pick up MCP servers added while it is open.
+
+## Each person, each machine
+
+Every person runs `init` in their own checkout with their own sign-in. The team, the project and the MCP server names (`clave-<agent>`) are the same everywhere; the token inside is the person's own agent token, so clave records who did what (`agent:coder@ayse`).
+
+## Options
+
+| Option | |
+|---|---|
+| `--org <slug>` | Org to use (default: ask) |
+| `--project <key>` | Existing project key (default: match this repository) |
+| `--agents <a,b>` | `init`: agent names, e.g. `coder,reviewer` (default: ask) |
+| `--unit <key>` | `add agent`: the unit it works for (default: ask) |
+| `--repo <remote>` | `add project`: repository instead of this folder's git remote |
+| `--yes` | Accept the defaults without asking |
+| `--no-open` | Print the sign-in link instead of opening the browser |
+| `--no-claude` | Write `.mcp.json` instead of using the `claude` CLI (`.env.clave` is written either way) |
+| `--url <site>` | clave site (default `https://clave.one`, or `CLAVE_URL`) |
+
+Start Claude Code in the repository after `init` or `add agent`; servers added while a session is open load at the next session start.
+
+Guide for AI agents: https://clave.one/getting-started-ai.md

package/bin/clave.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// clave CLI: `clave init` bu repoyu clave'e bağlar (giriş, proje, kendi agent'ların, MCP ayarı);
+// `clave add unit|project|agent <ad>` var olan kuruluma ekler.
+import { readFileSync } from "node:fs";
+import { add, explain, init } from "../src/init.mjs";
+
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+const has = (name) => args.includes(`--${name}`);
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const help = `clave ${version}: connect this repository to clave (https://clave.one)
+
+Usage: npx @dotlabshq/clave init [options]
+       npx @dotlabshq/clave add unit <name>       (owner or admin)
+       npx @dotlabshq/clave add project <name>    (owner or admin; repo = this folder's git remote)
+       npx @dotlabshq/clave add agent <name>      (your own agent)
+
+  init signs you in through the browser, picks the org and project, registers
+  your agents (id name@your-handle), issues their tokens and adds them to Claude
+  Code for this project. It stops if the repository is already set up: use add.
+  Tokens are never printed; they go to a git-ignored .env.clave and the MCP
+  config holds only the variable name (\${CLAVE_TOKEN_<AGENT>}).
+
+Options:
+  --org <slug>          Org to use (default: ask)
+  --project <key>       Existing project key (default: match this repository)
+  --agents <a,b>        init: agent names (default: ask; "coder")
+  --unit <key>          add agent: the unit it works for (default: ask)
+  --repo <remote>       add project: repository instead of this folder's remote
+  --yes                 Accept the defaults without asking
+  --no-open             Don't open the browser; print the sign-in link only
+  --no-claude           Don't use the claude CLI; write .mcp.json
+  --url <site>          clave site (default: https://clave.one)
+  -h, --help            This help
+  -v, --version         The version`;
+
+if (has("help") || args.includes("-h") || args.length === 0) { console.log(help); process.exit(0); }
+if (has("version") || args.includes("-v")) { console.log(version); process.exit(0); }
+const common = {
+  site: flag("url") ?? process.env.CLAVE_URL ?? "https://clave.one",
+  org: flag("org"), project: flag("project"),
+  yes: has("yes"), open: !has("no-open"), claude: has("no-claude") ? "never" : "auto",
+};
+const run = args[0] === "init" ? init({ ...common, agents: flag("agents") })
+  : args[0] === "add" ? add(args[1], args[2], { ...common, unit: flag("unit"), repo: flag("repo") })
+  : null;
+if (!run) { console.error(`Unknown command: ${args[0]}\n\n${help}`); process.exit(2); }
+run.catch((e) => { console.error(`clave: ${explain(e)}`); process.exit(1); });

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@dotlabshq/clave",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Set up clave (clave.one) in a repository: sign in, project, agents and MCP config for Claude Code in one command.",
+  "license": "MIT",
+  "homepage": "https://clave.one/docs/getting-started-ai",
+  "bin": {
+    "clave": "bin/clave.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "node --check bin/clave.mjs && for f in src/*.mjs; do node --check $f || exit 1; done"
+  }
 }

package/src/agentsmd.mjs

@@ -0,0 +1,44 @@
+// AGENTS.md / CLAUDE.md'ye clave bloğu: her oturum aynı başlasın. Varsa blok yenilenir.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const START = "<!-- clave:start -->", END = "<!-- clave:end -->";
+
+export function block({ project, servers, site }) {
+  return `${START}
+## Task management: clave
+
+- clave project: ${project}
+- MCP server${servers.length > 1 ? "s" : ""}: ${servers.map((s) => `\`${s}\``).join(", ")} (${site}/v1/mcp). Setup guide: ${site}/getting-started-ai.md
+- Start every session with \`session_start { project: "${project}" }\`: read the brief, the rules (binding) and the gotchas.
+- Before starting work, find or create its item in clave; claim it, report progress, finish with evidence.
+- Ask before risky steps with \`request_approval\` (production, deletes, external publishing). Leave what the next session needs with \`remember\`.
+${END}
+`;
+}
+
+/** Hangi dosya: CLAUDE.md varsa o, yoksa AGENTS.md (yoksa oluşturulur). */
+export function targetFile(cwd) {
+  for (const f of ["AGENTS.md", "CLAUDE.md"]) if (existsSync(join(cwd, f))) return join(cwd, f);
+  return join(cwd, "AGENTS.md");
+}
+
+/** Dosyadaki clave bloğu: proje anahtarı ve sunucu adları; blok yoksa null. `clave init` buradan "zaten kurulu" der. */
+export function readBlock(path) {
+  if (!existsSync(path)) return null;
+  const s = readFileSync(path, "utf8");
+  const i = s.indexOf(START), j = s.indexOf(END);
+  if (i < 0 || j < i) return null;
+  const b = s.slice(i, j);
+  const project = b.match(/clave project: (\S+)/)?.[1] ?? "";
+  const servers = [...b.matchAll(/`(clave-[a-z0-9-]+)`/g)].map((m) => m[1]);
+  return { project, servers };
+}
+
+export function upsert(path, text) {
+  const old = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const i = old.indexOf(START), j = old.indexOf(END);
+  const next = i >= 0 && j > i ? old.slice(0, i) + text.trimEnd() + old.slice(j + END.length) : `${old}${old && !old.endsWith("\n\n") ? (old.endsWith("\n") ? "\n" : "\n\n") : ""}${text}`;
+  writeFileSync(path, next);
+  return old ? "updated" : "created";
+}

package/src/config.mjs

@@ -0,0 +1,57 @@
+// MCP ayarını yazar; secret ekrana ve modele hiç gelmez, ayar dosyalarına da girmez.
+// Secret her zaman git'e girmeyen .env.clave'de (0600); ayar yalnız değişken adını taşır: `${CLAVE_TOKEN_<AGENT>}`.
+// Claude Code varsa `claude mcp add --scope local` (bu makinedeki proje ayarı, repoya girmez), yoksa .mcp.json.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, chmodSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const envName = (agent) => `CLAVE_TOKEN_${agent.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+export const serverName = (agent) => `clave-${agent}`;
+/** Ayara yazılan değer: değişken referansı, secret değil. */
+export const bearerRef = (agent) => `Authorization: Bearer \${${envName(agent)}}`;
+
+export function hasClaude(run = spawnSync) {
+  const r = run("claude", ["--version"], { stdio: "ignore" });
+  return !r.error && r.status === 0;
+}
+
+/** Claude Code'a değişken referansıyla ekler; aynı adlı eski kayıt varsa önce siler. */
+export function addToClaude({ agent, mcpUrl, cwd, run = spawnSync }) {
+  const name = serverName(agent);
+  run("claude", ["mcp", "remove", "--scope", "local", name], { cwd, stdio: "ignore" });
+  const r = run("claude", ["mcp", "add", "--scope", "local", "--transport", "http", name, mcpUrl, "--header", bearerRef(agent)], { cwd, stdio: "ignore" });
+  if (r.error || r.status !== 0) throw new Error(`claude mcp add ${name} failed`);
+  return name;
+}
+
+/** .mcp.json (değişken adı; commit edilebilir). Var olan başka sunuculara dokunmaz. */
+export function writeMcpJson({ agents, mcpUrl, cwd }) {
+  const mcpPath = join(cwd, ".mcp.json");
+  const cfg = existsSync(mcpPath) ? JSON.parse(readFileSync(mcpPath, "utf8")) : {};
+  cfg.mcpServers ??= {};
+  for (const { agent } of agents) {
+    cfg.mcpServers[serverName(agent)] = { type: "http", url: mcpUrl, headers: { Authorization: `Bearer \${${envName(agent)}}` } };
+  }
+  writeFileSync(mcpPath, JSON.stringify(cfg, null, 2) + "\n");
+  return mcpPath;
+}
+
+/** .env.clave (secret'lar, 0600) ve .gitignore'a .env.clave. Aynı agent'ın eski satırı yenilenir. */
+export function writeEnv({ agents, cwd }) {
+  const envPath = join(cwd, ".env.clave");
+  const old = existsSync(envPath) ? readFileSync(envPath, "utf8").split("\n").filter((l) => l && !agents.some((a) => l.startsWith(`${envName(a.agent)}=`))) : [];
+  writeFileSync(envPath, [...old, ...agents.map((a) => `${envName(a.agent)}=${a.secret}`)].join("\n") + "\n");
+  chmodSync(envPath, 0o600);
+
+  const gi = join(cwd, ".gitignore");
+  const lines = existsSync(gi) ? readFileSync(gi, "utf8").split("\n") : [];
+  if (!lines.includes(".env.clave")) appendFileSync(gi, `${lines.length && lines[lines.length - 1] !== "" ? "\n" : ""}.env.clave\n`);
+  return envPath;
+}
+
+/** .mcp.json'daki clave sunucuları (clave-*). */
+export function mcpJsonServers(cwd) {
+  const p = join(cwd, ".mcp.json");
+  if (!existsSync(p)) return [];
+  try { return Object.keys(JSON.parse(readFileSync(p, "utf8")).mcpServers ?? {}).filter((s) => s.startsWith("clave-")); } catch { return []; }
+}

package/src/http.mjs

@@ -0,0 +1,23 @@
+// clave'in REST'i: site adresi + /v1/mcp (Flect önek siler; yerelde web aynı yolu API'ye geçirir).
+// Kimlik cihaz akışından gelen kişi token'ı; org'a bağlı çağrılar X-Org-Id ile gider.
+
+export class ApiError extends Error {
+  constructor(status, code, message) { super(message || code); this.status = status; this.code = code; }
+}
+
+export function urls(site) {
+  const base = site.replace(/\/+$/, "");
+  return { site: base, api: `${base}/v1/mcp`, auth: `${base}/v1/auth`, mcp: `${base}/v1/mcp` };
+}
+
+export function client({ api, token, org = null, fetchImpl = fetch }) {
+  return async function call(method, path, body) {
+    const headers = { authorization: `Bearer ${token}`, accept: "application/json" };
+    if (org) headers["x-org-id"] = org;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    const r = await fetchImpl(`${api}${path}`, { method, headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
+    const data = await r.json().catch(() => ({}));
+    if (!r.ok) throw new ApiError(r.status, data.error ?? `http_${r.status}`, data.message ?? data.error);
+    return data;
+  };
+}

package/src/init.mjs

@@ -0,0 +1,202 @@
+// `clave init`: bu repoyu bu makinede clave'e ilk kez bağlar, kişinin kendi kimliğiyle (cihaz girişi):
+// org → proje → birim → kişinin kendi agent'ları ve token'ları → MCP ayarı → AGENTS.md. Token'lar ekrana basılmaz.
+// Repo zaten bağlıysa durur ve `clave add`'e yollar. `clave add unit|project|agent`: var olan kuruluma parça ekler;
+// unit ve project sahip/yönetici ister (koordinatör, kişi token'ıyla), agent kişinin kendisinindir.
+import { spawnSync } from "node:child_process";
+import { hostname } from "node:os";
+import { basename } from "node:path";
+import { ApiError, client, urls } from "./http.mjs";
+import { deviceLogin, openBrowser } from "./login.mjs";
+import { prompter } from "./prompt.mjs";
+import { addToClaude, hasClaude, mcpJsonServers, serverName, writeEnv, writeMcpJson } from "./config.mjs";
+import { block, readBlock, targetFile, upsert } from "./agentsmd.mjs";
+
+const NAME = /^[a-z0-9][a-z0-9-]{1,31}$/;
+const MANAGERS = new Set(["owner", "admin"]);
+
+/** git remote → "github.com/owner/repo"; remote yoksa klasör adı. */
+export function repoOf(cwd, run = spawnSync) {
+  const r = run("git", ["config", "--get", "remote.origin.url"], { cwd, encoding: "utf8" });
+  const raw = !r.error && r.status === 0 ? String(r.stdout).trim() : "";
+  const m = raw.match(/^(?:https?:\/\/|ssh:\/\/)?(?:[^@/]+@)?([^/:]+)[/:](.+?)(?:\.git)?\/?$/);
+  return { remote: m ? `${m[1]}/${m[2]}` : "", name: m ? basename(m[2]) : basename(cwd) };
+}
+
+export function matchProject(projects, repo) {
+  const live = projects.filter((p) => !p.archived);
+  const norm = (s) => String(s ?? "").toLowerCase().replace(/\.git$/, "").replace(/\/+$/, "");
+  return live.find((p) => repo.remote && p.repo && (norm(repo.remote).endsWith(norm(p.repo)) || norm(p.repo).endsWith(norm(repo.remote))))
+    ?? live.find((p) => p.key === repo.name.toLowerCase() || norm(p.name) === norm(repo.name)) ?? null;
+}
+
+/** Bu repo bu makinede kurulu mu: AGENTS.md/CLAUDE.md bloğu ya da .mcp.json'daki clave sunucuları. */
+export function existingSetup(cwd) {
+  const fromBlock = readBlock(targetFile(cwd));
+  const servers = [...new Set([...(fromBlock?.servers ?? []), ...mcpJsonServers(cwd)])];
+  return fromBlock || servers.length ? { project: fromBlock?.project ?? "", servers } : null;
+}
+
+/** Giriş ve org seçimi; her komutun ortak başı. `manage`: sahip/yönetici gerekir. */
+async function session(opts, { manage = false } = {}) {
+  const { site = "https://clave.one", open = true, yes = false, log = (s) => console.log(s), fetchImpl = fetch, loginInterval } = opts;
+  const u = urls(site);
+  const ask = opts.prompter ?? prompter({ yes });
+  const token = opts.token ?? await deviceLogin({ auth: u.auth, log, open: open ? openBrowser : null, fetchImpl, ...(loginInterval ? { interval: loginInterval } : {}) });
+  const me = client({ api: u.api, token, fetchImpl });
+  const { orgs } = await me("GET", "/orgs");
+  const usable = orgs.filter((o) => o.role !== "viewer" && (!manage || MANAGERS.has(o.role)));
+  if (usable.length === 0) {
+    if (!orgs.length) throw new Error(`You have no org yet. Create one at ${u.site}/start, then run this again.`);
+    throw new Error(manage ? "This needs an owner or admin of the org; ask one to run it." : "You are a viewer in every org; ask an owner or admin for the member role.");
+  }
+  const pick = opts.org ? usable.find((o) => o.slug === opts.org || o.id === opts.org) : null;
+  if (opts.org && !pick) throw new Error(`No org "${opts.org}" where you are ${manage ? "owner or admin" : "a member"}.`);
+  const org = pick ?? await ask.choose("Org", usable.map((o) => ({ label: `${o.name} (${o.slug})`, ...o })));
+  const call = client({ api: u.api, token, org: org.slug, fetchImpl });
+  log(`Org: ${org.name}`);
+  return { u, ask, log, org, call, manager: MANAGERS.has(org.role) };
+}
+
+/** Kişinin kendi agent'ları: kayıt (varsa kendi kaydı kullanılır) ve her birine bir token. Secret yalnız dönüşte. */
+async function registerAgents(call, names, unit, log) {
+  const bad = names.find((n) => !NAME.test(n));
+  if (bad) throw new Error(`"${bad}" is not a valid agent name: 2–32 lowercase letters, digits, dashes.`);
+  const { agents: existing, me } = await call("GET", "/agents");
+  const issued = [];
+  for (const agent of names) {
+    let id = existing.find((a) => a.name === agent && (!a.owner || a.owner === me))?.id;
+    if (!id) { ({ id } = await call("POST", "/agents", { name: agent, unit })); log(`Agent registered: ${id}`); }
+    const { secret } = await call("POST", `/agents/${encodeURIComponent(id)}/tokens`, { label: hostname().slice(0, 30) });
+    issued.push({ agent, id, secret });
+  }
+  return issued;
+}
+
+/** MCP ayarı: secret .env.clave'ye, ayara değişken adı. Claude Code varsa local scope, yoksa .mcp.json. */
+function configure({ issued, u, cwd, useClaude, run, log }) {
+  const claudeOk = useClaude === "never" ? false : useClaude === "always" ? true : hasClaude(run);
+  const envPath = writeEnv({ agents: issued, cwd });
+  let servers;
+  if (claudeOk) {
+    servers = issued.map(({ agent }) => addToClaude({ agent, mcpUrl: u.mcp, cwd, run }));
+    log(`Claude Code: added ${servers.join(", ")} for this project (local scope, by variable name; not in the repository).`);
+  } else {
+    const mcpPath = writeMcpJson({ agents: issued, mcpUrl: u.mcp, cwd });
+    servers = issued.map(({ agent }) => serverName(agent));
+    log(`Wrote ${basename(mcpPath)} (variable names only).`);
+    log(`Codex: add [mcp_servers.${servers[0]}] url = "${u.mcp}", bearer_token_env_var = "CLAVE_TOKEN_${issued[0].agent.toUpperCase().replace(/[^A-Z0-9]/g, "_")}" to ~/.codex/config.toml`);
+  }
+  log(`Tokens are in ${basename(envPath)} (git-ignored, 0600). Load it before starting your client: set -a; . ./.env.clave; set +a  (or export those variables in your shell profile).`);
+  issued.forEach((x) => { x.secret = ""; });
+  return { servers, claudeOk };
+}
+
+export async function init(opts) {
+  const { cwd = process.cwd(), claude: useClaude = "auto", run = spawnSync } = opts;
+  const done = existingSetup(cwd);
+  if (done) {
+    throw new Error(`This repository is already set up${done.project ? ` (project ${done.project}` : " ("}${done.servers.length ? `${done.project ? ", " : ""}servers ${done.servers.join(", ")}` : ""}). To add an agent: clave add agent <name>. To add a unit or project to the plan: clave add unit|project <name> (owner or admin).`);
+  }
+  const { u, ask, log, org, call, manager } = await session(opts);
+  try {
+    // Proje: repo'dan eşleşen ya da yeni (yeni açmak sahip/yönetici işi).
+    const setup = await call("GET", "/setup");
+    const repo = repoOf(cwd, run);
+    let project = opts.project ? setup.projects.find((p) => p.key === opts.project) : matchProject(setup.projects, repo);
+    if (opts.project && !project) throw new Error(`No project "${opts.project}" in ${org.name}.`);
+    if (project && !opts.project && !(await ask.confirm(`Use project "${project.name}" (${project.key})?`, true))) project = null;
+    if (!project) {
+      if (!manager) throw new Error(`No project for this repository in ${org.name}. Ask an owner or admin to run: clave add project ${repo.name}`);
+      const name = await ask.ask("New project name", repo.name);
+      const lines = setup.lines.filter((l) => !l.archived);
+      const { key } = await call("POST", "/setup/projects", { name, repo: repo.remote, line: lines[0]?.key ?? "" });
+      project = { key, name };
+      log(`Project created: ${name} (${key})`);
+    } else log(`Project: ${project.name} (${project.key})`);
+
+    // Birim: var olanlardan seç; yoksa sahip/yönetici açar.
+    const units = setup.units.filter((x) => !x.archived);
+    let unit;
+    if (units.length) {
+      const pickU = await ask.choose("Unit your agents work for", units.map((x) => ({ label: x.name, ...x })));
+      unit = pickU.key;
+      log(`Unit: ${pickU.name}`);
+    } else {
+      if (!manager) throw new Error(`${org.name} has no unit yet. Ask an owner or admin to run: clave add unit <name>`);
+      const name = await ask.ask("No units yet. Name the team that owns the work", "Core team");
+      unit = (await call("POST", "/setup/units", { name })).key;
+      log(`Unit created: ${name}`);
+    }
+    if (!setup.lines.some((l) => !l.archived) || !setup.goals.some((g) => !g.archived)) {
+      log(`Tip: the plan has no business line or goal yet. Finish it at ${u.site}/app/welcome`);
+    }
+
+    // Kişinin kendi agent'ları ve MCP ayarı
+    const wanted = (opts.agents ?? await ask.ask("Your agents to set up (comma-separated)", "coder")).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+    const issued = await registerAgents(call, wanted, unit, log);
+    const { servers, claudeOk } = configure({ issued, u, cwd, useClaude, run, log });
+
+    // AGENTS.md
+    const file = targetFile(cwd);
+    if (await ask.confirm(`Add the clave block to ${basename(file)}?`, true)) {
+      const how = upsert(file, block({ project: project.key, servers, site: u.site }));
+      log(`${basename(file)} ${how}.`);
+    }
+
+    log(`\nDone. Start your agent in this repository (a new session: servers load at session start); its first call is session_start { project: "${project.key}" }.`);
+    return { org: org.slug, project: project.key, unit, agents: wanted, ids: issued.map((x) => x.id), servers, claude: claudeOk };
+  } finally {
+    ask.close?.();
+  }
+}
+
+/**
+ * `clave add unit|project|agent <name>`: var olan kuruluma ekler.
+ * unit/project: sahip/yönetici (koordinatör, kişi token'ıyla). agent: kişinin kendisinin; MCP ayarı ve AGENTS.md bloğu güncellenir.
+ */
+export async function add(kind, name, opts) {
+  const { cwd = process.cwd(), claude: useClaude = "auto", run = spawnSync } = opts;
+  if (!["unit", "project", "agent"].includes(kind)) throw new Error(`clave add: what to add is unit, project or agent (got "${kind ?? ""}")`);
+  if (!name) throw new Error(`clave add ${kind}: give it a name`);
+  const { u, ask, log, org, call } = await session(opts, { manage: kind !== "agent" });
+  try {
+    if (kind === "unit") {
+      const { key } = await call("POST", "/setup/units", { name });
+      log(`Unit created: ${name} (${key}). People run clave init in their repositories and pick it.`);
+      return { org: org.slug, unit: key };
+    }
+    if (kind === "project") {
+      const setup = await call("GET", "/setup");
+      const repo = repoOf(cwd, run);
+      const lines = setup.lines.filter((l) => !l.archived);
+      const { key } = await call("POST", "/setup/projects", { name, repo: opts.repo ?? repo.remote, line: lines[0]?.key ?? "" });
+      log(`Project created: ${name} (${key})${repo.remote ? ` for ${repo.remote}` : ""}. People run clave init in that repository.`);
+      return { org: org.slug, project: key };
+    }
+    // agent: birim kuruludan ya da --unit; kurulum yoksa da çalışır (yalnız MCP ayarı yazılır).
+    const done = existingSetup(cwd);
+    const setup = await call("GET", "/setup");
+    const units = setup.units.filter((x) => !x.archived);
+    let unit = opts.unit;
+    if (unit && !units.some((x) => x.key === unit)) throw new Error(`No unit "${unit}" in ${org.name}.`);
+    if (!unit && units.length) { const pickU = await ask.choose("Unit the agent works for", units.map((x) => ({ label: x.name, ...x }))); unit = pickU.key; }
+    const issued = await registerAgents(call, [name.toLowerCase()], unit ?? "", log);
+    const { servers, claudeOk } = configure({ issued, u, cwd, useClaude, run, log });
+    const project = opts.project ?? done?.project ?? "";
+    if (project) {
+      const all = [...new Set([...(done?.servers ?? []), ...servers])];
+      upsert(targetFile(cwd), block({ project, servers: all, site: u.site }));
+      log(`${basename(targetFile(cwd))} updated (${all.join(", ")}).`);
+    }
+    log(`\nDone. Open a new session to use ${servers[0]} (a running session does not pick up new servers).`);
+    return { org: org.slug, agent: issued[0].id, servers, claude: claudeOk };
+  } finally {
+    ask.close?.();
+  }
+}
+
+/** API hatasını kullanıcının diline çevirir (bin). */
+export function explain(e) {
+  if (e instanceof ApiError && e.status === 403) return `${e.message} (this needs an owner or admin; a member manages only their own agents)`;
+  return e.message;
+}

package/src/login.mjs

@@ -0,0 +1,32 @@
+// Tarayıcıyla giriş: auth-service'in CLI cihaz akışı. /start bir onay adresi verir, kişi tarayıcıda clave'e
+// girip onaylar, /poll kişi token'ını döner (24 saat). Token yalnız bellekte tutulur, diske yazılmaz.
+import { spawn } from "node:child_process";
+
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  // Tarayıcı yoksa (container, SSH) spawn ENOENT'i senkron değil `error` olayıyla verir: dinlenmezse süreç düşer.
+  // Bağlantı zaten ekranda; açılamaması hata değildir.
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch { return false; }
+}
+
+export async function deviceLogin({ auth, log, open = openBrowser, fetchImpl = fetch, interval = 2000, timeout = 600_000 }) {
+  const r = await fetchImpl(`${auth}/start`);
+  if (!r.ok) throw new Error(`Sign-in could not start (HTTP ${r.status})`);
+  const { state, url } = await r.json();
+  log(`Sign in to clave in your browser:\n  ${url}`);
+  if (open) open(url);
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    await new Promise((res) => setTimeout(res, interval));
+    const p = await fetchImpl(`${auth}/poll/${encodeURIComponent(state)}`).then((x) => x.json()).catch(() => ({ status: "pending" }));
+    if (p.status === "done" && p.token) return p.token;
+    if (p.status === "expired") throw new Error("The sign-in link expired. Run the command again.");
+  }
+  throw new Error("Timed out waiting for the sign-in.");
+}

package/src/prompt.mjs

@@ -0,0 +1,31 @@
+// Soru-cevap: --yes ile varsayılanlar, yoksa terminalden.
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+export function prompter({ yes = false, input = stdin, output = stdout } = {}) {
+  let rl = null;
+  const line = async (q) => {
+    rl ??= createInterface({ input, output });
+    return (await rl.question(q)).trim();
+  };
+  return {
+    async ask(q, def = "") {
+      if (yes) return def;
+      const a = await line(def ? `${q} [${def}]: ` : `${q}: `);
+      return a || def;
+    },
+    async confirm(q, def = true) {
+      if (yes) return def;
+      const a = (await line(`${q} [${def ? "Y/n" : "y/N"}]: `)).toLowerCase();
+      return a ? a.startsWith("y") : def;
+    },
+    async choose(q, options, defIndex = 0) {
+      if (yes || options.length === 1) return options[defIndex];
+      options.forEach((o, i) => output.write(`  ${i + 1}) ${o.label}\n`));
+      const a = await line(`${q} [${defIndex + 1}]: `);
+      const n = Number(a || defIndex + 1);
+      return options[Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : defIndex];
+    },
+    close() { rl?.close(); },
+  };
+}