overlord-cli 0.2606041130.1 → 0.2606041635.0

package/README.md

@@ -107,6 +107,7 @@ Top-level commands (see `ovld help`):
 - `<agent> "<prompt>"` - create a ticket from the prompt (project inferred from the current directory) and launch the agent on it in one step, e.g. `ovld claude "fix the flaky login test" --model opus`. Built-in agents need an installed connector (`ovld setup <agent>`, override with `--allow-uninstalled`); your custom agents launch by id. Flags after a standalone `--` pass through to the agent binary.
 - `attach` - search tickets and launch an agent interactively (`ovld attach [ticketId] [agent]`)
 - `create` - create a ticket with numbered project selection; supports `--agent`, `--model`, `--delegate` (same delegate flags as `ovld protocol create`)
+- `create-project` - create a project, registering the current directory (or `--directory`) as its primary resource in one step; `--no-directory` makes a bare project (alias for `ovld protocol create-project`)
 - `prompt` - create a ticket, then launch an agent on it
 - `auth` - `login`, `status`, `repair` (shared Desktop/CLI credentials), or `logout`
 - `tickets` - `create` or `list` (optional `--status`)
@@ -150,6 +151,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-download-url` - get a signed download URL for an existing objective attachment
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 - `get-device` / `update-device` - register the caller machine (per organization + user + fingerprint) and rename its label
+- `create-project` - create a project and, when a `--directory` + `--device-fingerprint` are given, register it as the project's primary resource in one step
 - `list-project-resources` / `add-project-resource` / `update-project-resource` - manage filesystem directories tied to a project device
 - `request-execution` / `claim-execution` / `list-execution-requests` / `clear-execution-requests` / `complete-execution-launch` / `fail-execution-launch` - durable runner queue operations used by auto-advance and manual Run
 - `list-organizations` - list every organization the authenticated user (or agent token) belongs to; the runner uses this to poll all of your organizations, not just the one stored at login

package/bin/_cli/index.mjs

@@ -33,6 +33,7 @@ Usage:
   ${primaryCommand} attach [ticketId] [agent]  Search tickets and launch an agent (interactive)
   ${primaryCommand} create "<objective>"       Create a ticket with numbered project selection; supports --agent/--model/--delegate
   ${primaryCommand} prompt "<objective>"       Create a ticket, then launch an agent on it
+  ${primaryCommand} create-project --name "<name>"  Create a project, optionally linking a directory in one step
   ${primaryCommand} add-cwd                   Register the current directory as a project resource (interactive)
   ${primaryCommand} onboard                   Create an account, project, cwd link, and onboarding ticket
   ${primaryCommand} auth <subcommand>          Login, logout, repair, or check auth status
@@ -112,6 +113,12 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'create-project') {
+    // Friendly top-level alias for `ovld protocol create-project`.
+    await runProtocolCommand('create-project', rest);
+    return;
+  }
+
   if (command === 'add-cwd') {
     const { runAddCwdCommand } = await import('./add-cwd.mjs');
     await runAddCwdCommand(rest);

package/bin/_cli/onboard.mjs

@@ -105,14 +105,27 @@ async function promptForYes(question, defaultYes = true) {
   }
 }
 
-function buildSignupUrl(platformUrl, verificationUri, name) {
+function buildSignupUrl(platformUrl, verificationUri, name, invite) {
   const verificationUrl = new URL(verificationUri);
   const signupUrl = new URL('/signup', platformUrl);
   signupUrl.searchParams.set('next', `${verificationUrl.pathname}${verificationUrl.search}`);
   if (name) signupUrl.searchParams.set('name', name);
+  // Pre-fill the invited email and accept the invite after signup (web fallback parity).
+  if (invite) signupUrl.searchParams.set('invite', invite);
   return signupUrl.toString();
 }
 
+/**
+ * Accept either a bare invitation token or a full `…/invite/<token>` URL pasted
+ * from the invite email, returning the bare token (or '' when not provided).
+ */
+function normalizeInviteToken(raw) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (!value) return '';
+  const match = value.match(/\/invite\/([^/?#]+)/);
+  return match ? decodeURIComponent(match[1]) : value;
+}
+
 async function completeCliOnboarding(platformUrl, localSecret, credentials, payload) {
   const res = await fetch(`${platformUrl}/api/auth/cli-onboarding`, {
     method: 'POST',
@@ -141,7 +154,7 @@ export async function runOnboardCommand(args) {
   const flags = parseFlags(args);
 
   if (flags.help === true || flags.h === true || args[0] === 'help') {
-    console.log(`Usage: ovld onboard [--name <name>] [--organization-name <name>] [--project-name <name>] [--directory <path>] [--yes] [--no-desktop]
+    console.log(`Usage: ovld onboard [--name <name>] [--organization-name <name>] [--project-name <name>] [--directory <path>] [--invite <token|url>] [--yes] [--no-desktop]
 
 Creates an Overlord account setup from the terminal:
   1. collects your name, organization, project, and repository directory
@@ -149,21 +162,32 @@ Creates an Overlord account setup from the terminal:
   3. creates the organization/project, links this directory, and creates the first onboarding ticket
   4. opens the Desktop download page, or the web project when --no-desktop is used
 
+With --invite <token>, joins the inviting organization (from an invite email)
+with the invited role instead of creating a new organization; the organization
+prompt is skipped. Accepts a bare token or a full /invite/<token> URL.
+
 Run this from the repository you want Overlord agents to work in.`);
     return;
   }
 
+  const inviteToken = normalizeInviteToken(flags.invite ?? flags['invite-code']);
+
   const directoryPath = path.resolve(trimFlag(flags, 'directory') || process.cwd());
   const directoryName = path.basename(directoryPath) || 'My project';
   const inferredName = os.userInfo().username || 'User';
   const name = trimFlag(flags, 'name') || (await promptForValue('Your name', inferredName));
-  const organizationName =
-    trimFlag(flags, 'organization-name') || (await promptForValue('Organization name', name));
+  // On the invite path the org comes from the invitation, so skip the org prompt.
+  const organizationName = inviteToken
+    ? trimFlag(flags, 'organization-name')
+    : trimFlag(flags, 'organization-name') || (await promptForValue('Organization name', name));
   const projectName =
     trimFlag(flags, 'project-name') || (await promptForValue('Project name', directoryName));
 
-  if (!name || !organizationName || !projectName) {
-    throw new Error('Name, organization name, and project name are required.');
+  if (!name || !projectName) {
+    throw new Error('Name and project name are required.');
+  }
+  if (!inviteToken && !organizationName) {
+    throw new Error('Organization name is required (or pass --invite <token> to join an org).');
   }
 
   const storedCredentials = loadCredentials();
@@ -176,7 +200,7 @@ Run this from the repository you want Overlord agents to work in.`);
 
   const credentials = await authLoginViaDeviceFlow(platformUrl, localSecret, {
     browserOpener: verificationUri => {
-      const signupUrl = buildSignupUrl(platformUrl, verificationUri, name);
+      const signupUrl = buildSignupUrl(platformUrl, verificationUri, name, inviteToken);
       console.log(`  Signup URL: ${signupUrl}`);
       openBrowser(signupUrl);
     }
@@ -186,12 +210,13 @@ Run this from the repository you want Overlord agents to work in.`);
   const deviceFingerprint = readOrCreateDeviceFingerprint(flags);
   const result = await completeCliOnboarding(resolvedPlatformUrl, localSecret, credentials, {
     name,
-    organizationName,
+    ...(organizationName ? { organizationName } : {}),
     projectName,
     directoryPath,
     deviceFingerprint,
     deviceHostname: os.hostname(),
-    devicePlatform: process.platform
+    devicePlatform: process.platform,
+    ...(inviteToken ? { inviteToken } : {})
   });
 
   saveCredentials({
@@ -216,9 +241,14 @@ Run this from the repository you want Overlord agents to work in.`);
 
   console.log('\nOverlord setup complete.');
   console.log(`  Organization: ${result.organization.organizationName}`);
+  if (result.organization.role) {
+    console.log(`  Role: ${result.organization.role}`);
+  }
   console.log(`  Project: ${result.project.name}`);
   console.log(`  Directory: ${directoryPath}`);
-  console.log(`  Onboarding ticket: ${result.ticket.reference ?? result.ticket.id}`);
+  if (result.ticket) {
+    console.log(`  Onboarding ticket: ${result.ticket.reference ?? result.ticket.id}`);
+  }
 
   const skipDesktop = flags['no-desktop'] === true || flags.desktop === 'false';
   const autoYes = flags.yes === true || flags.y === true;

package/bin/_cli/protocol.mjs

@@ -1982,6 +1982,135 @@ async function protocolUpdateProjectResource(args) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// ---------------------------------------------------------------------------
+// create-project (create a project, optionally registering a primary directory)
+// ---------------------------------------------------------------------------
+
+async function protocolCreateProject(args) {
+  const flags = parseFlags(args);
+
+  if (flags.help === true || flags.h === true) {
+    console.log(`Usage: ovld create-project --name "<name>" [options]
+
+Create a project. By default the current working directory is registered as the
+project's primary resource in the same call (one-step setup).
+
+Options:
+  --name <text>              Project name (required)
+  --color <#rrggbb>          Project color (defaults to a soft rose)
+  --directory <path>         Directory to register as the primary resource
+                             (defaults to the current working directory)
+  --no-directory             Create a bare project without registering a directory
+  --device-fingerprint <fp>  Device for the directory (or OVERLORD_DEVICE_FINGERPRINT;
+                             auto-generated when omitted)
+  --label <text>             Label for the registered directory
+  --is-primary <true|false>  Override primary status (directory defaults to primary)
+  --organization-id <id>     Create in a specific organization (defaults to membership)
+
+This command is also available as \`ovld protocol create-project\`.`);
+    return;
+  }
+
+  const { platformUrl, bearerToken, localSecret, organizationId } =
+    await resolveProtocolAuthForFlags(flags);
+  const timeoutMs = resolveTimeout(flags);
+
+  const name = typeof flags.name === 'string' ? flags.name.trim() : '';
+  if (!name) {
+    console.error('Error: --name is required');
+    process.exit(1);
+  }
+
+  // A directory makes project creation a one-step process: the project is
+  // created and the directory is registered as its primary resource together.
+  // Pass --no-directory (or --directory=false) to create a bare project.
+  const directoryRequested = !(flags.directory === false || flags.directory === 'false');
+  let directoryPath = '';
+  if (directoryRequested) {
+    directoryPath = path.resolve(
+      typeof flags.directory === 'string' && flags.directory.trim()
+        ? flags.directory.trim()
+        : process.cwd()
+    );
+    if (!fs.existsSync(directoryPath)) {
+      console.error(`Error: Directory does not exist: ${directoryPath}`);
+      process.exit(1);
+    }
+  }
+
+  let deviceFingerprint = '';
+  if (directoryPath) {
+    deviceFingerprint = String(
+      flags['device-fingerprint'] ?? process.env.OVERLORD_DEVICE_FINGERPRINT ?? ''
+    ).trim();
+    if (!deviceFingerprint) {
+      const { readOrCreateDeviceFingerprint } = await import('./runner.mjs');
+      deviceFingerprint = readOrCreateDeviceFingerprint(flags);
+    }
+  }
+
+  const isPrimary =
+    flags['is-primary'] !== undefined
+      ? flags['is-primary'] === true || flags['is-primary'] === 'true'
+      : flags.primary !== undefined
+        ? !(flags.primary === false || flags.primary === 'false')
+        : undefined;
+
+  const body = {
+    name,
+    ...(typeof flags.color === 'string' && flags.color.trim() ? { color: flags.color.trim() } : {}),
+    ...(directoryPath
+      ? {
+          directoryPath,
+          deviceFingerprint,
+          ...(isPrimary !== undefined ? { isPrimary } : {}),
+          ...(typeof flags.label === 'string' ? { label: flags.label } : {}),
+          ...(flags['device-hostname']
+            ? { deviceHostname: String(flags['device-hostname']) }
+            : { deviceHostname: os.hostname() }),
+          ...(flags['device-platform']
+            ? { devicePlatform: String(flags['device-platform']) }
+            : { devicePlatform: process.platform }),
+          ...(flags['device-port'] != null ? { devicePort: Number(flags['device-port']) } : {})
+        }
+      : {})
+  };
+
+  const data = await apiPost(
+    platformUrl,
+    bearerToken,
+    localSecret,
+    organizationId,
+    '/api/protocol/create-project',
+    body,
+    timeoutMs
+  );
+  console.log(JSON.stringify(data, null, 2));
+
+  if (data.project?.id) {
+    process.stderr.write(`\nPROJECT_ID=${data.project.id}\n`);
+  }
+  if (data.resource?.id) {
+    process.stderr.write(`RESOURCE_ID=${data.resource.id}\n`);
+  }
+
+  // Write .overlord/project.json so future cwd-based resolution finds the project.
+  if (directoryPath && data.project?.id && data.project?.name) {
+    try {
+      const { upsertLocalOverlordConfig } = await import('./local-config.mjs');
+      const result = await upsertLocalOverlordConfig({
+        directoryPath,
+        project: { id: data.project.id, name: data.project.name }
+      });
+      process.stderr.write(`OVERLORD_CONFIG=${result.filePath} (${result.action})\n`);
+    } catch (configError) {
+      process.stderr.write(
+        `\nWarning: could not write .overlord/project.json: ${configError instanceof Error ? configError.message : configError}\n`
+      );
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // execution requests (durable runner queue)
 // ---------------------------------------------------------------------------
@@ -2750,6 +2879,7 @@ Subcommands:
   attachment-upload-file      Prepare, upload, and finalize a local file in one command
   get-device                  Identify / register the current device and return its label
   update-device               Rename this device's label (must be lowercase kebab-case)
+  create-project              Create a project, optionally linking the current directory in one step
   list-project-resources      List resource directories registered for a project
   add-project-resource        Register a local directory as a project resource on this device
   update-project-resource     Update a resource directory's path, label, or primary status
@@ -3180,6 +3310,20 @@ update-device:
     --device-fingerprint <fp>  (or OVERLORD_DEVICE_FINGERPRINT env var)
     --label <label>            Lowercase kebab-case, unique within org
 
+create-project:
+  Required:
+    --name <text>              Project name
+  Optional:
+    --color <#rrggbb>          Project color (defaults to a soft rose)
+    --directory <path>         Register this directory as the project's primary resource
+                               in one step (defaults to the current working directory;
+                               pass --no-directory to create a bare project)
+    --device-fingerprint <fp>  Device for the directory (or OVERLORD_DEVICE_FINGERPRINT;
+                               auto-generated when omitted)
+    --label <text>             Label for the registered directory
+    --is-primary <true|false>  Override primary status (directory defaults to primary)
+    --organization-id <id>     Create in a specific organization (defaults to your membership)
+
 list-project-resources:
   Required:
     --project-id <uuid>
@@ -3322,6 +3466,8 @@ Examples:
 EOF
   ovld protocol get-device --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
   ovld protocol update-device --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT --label work-macbook
+  ovld protocol create-project --name "Acme Web" --directory /path/to/repo
+  ovld protocol create-project --name "Acme Web" --no-directory
   ovld protocol list-project-resources --project-id <project-uuid>
   ovld protocol list-project-resources --project-id <project-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
   ovld protocol add-project-resource --project-id <project-uuid> --device-fingerprint $OVERLORD_DEVICE_FINGERPRINT
@@ -3476,6 +3622,10 @@ EOF
     await protocolUpdateDevice(args);
     return;
   }
+  if (subcommand === 'create-project') {
+    await protocolCreateProject(args);
+    return;
+  }
   if (subcommand === 'list-project-resources') {
     await protocolListProjectResources(args);
     return;

package/bin/_cli/setup.mjs

@@ -1125,6 +1125,95 @@ function removeCursorBeforeSubmitHook(paths) {
 }
 
 
+// ---------------------------------------------------------------------------
+// Headless marketplace plugin install (Claude + Codex, via the agent CLI)
+// ---------------------------------------------------------------------------
+
+const OVERLORD_PLUGIN_NAME = 'overlord';
+const OVERLORD_MARKETPLACE_NAME = 'overlord-local';
+const OVERLORD_PLUGIN_KEY = `${OVERLORD_PLUGIN_NAME}@${OVERLORD_MARKETPLACE_NAME}`;
+const CLAUDE_MARKETPLACE_ROOT = path.join(os.homedir(), '.ovld', 'claude-marketplace');
+
+/**
+ * Run an agent CLI plugin command without throwing.
+ * `missing` is true when the agent binary is not on PATH (ENOENT).
+ *
+ * @returns {{ ok: boolean, missing: boolean, stdout: string, stderr: string }}
+ */
+function runAgentPluginCli(binary, args) {
+  try {
+    const stdout = execFileSync(binary, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return { ok: true, missing: false, stdout: stdout ?? '', stderr: '' };
+  } catch (err) {
+    return {
+      ok: false,
+      missing: err?.code === 'ENOENT',
+      stdout: err?.stdout?.toString?.() ?? '',
+      stderr: err?.stderr?.toString?.() ?? ''
+    };
+  }
+}
+
+/**
+ * Build the local marketplace wrapper under ~/.ovld/claude-marketplace and
+ * register + install the Overlord plugin through the `claude` CLI so the plugin
+ * (and its `overlord:overlord-ticket` skill) loads in every Claude session —
+ * including headless/pod environments where Overlord Desktop never ran. Mirrors
+ * the desktop installer's registerClaudeLocalMarketplace, but drives Claude's
+ * own plugin system instead of hand-writing its JSON.
+ *
+ * @returns {{ ok: boolean, missing: boolean }}
+ */
+function installClaudeMarketplacePlugin(sourceDir, version) {
+  const pluginDir = path.join(CLAUDE_MARKETPLACE_ROOT, 'plugins', OVERLORD_PLUGIN_NAME);
+  fs.mkdirSync(path.dirname(pluginDir), { recursive: true });
+  fs.rmSync(pluginDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, pluginDir, { recursive: true });
+
+  const marketplaceManifest = {
+    name: OVERLORD_MARKETPLACE_NAME,
+    owner: { name: 'Cooperativ', email: 'support@ovld.ai' },
+    metadata: {
+      description: 'Overlord plugin registered locally by the Overlord CLI.',
+      version
+    },
+    plugins: [
+      {
+        name: OVERLORD_PLUGIN_NAME,
+        source: `./plugins/${OVERLORD_PLUGIN_NAME}`,
+        description:
+          'Overlord ticket protocol workflow for Claude Code (attach/update/ask/deliver, slash commands, permission hook).',
+        version
+      }
+    ]
+  };
+  const manifestPath = path.join(CLAUDE_MARKETPLACE_ROOT, '.claude-plugin', 'marketplace.json');
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(marketplaceManifest, null, 2) + '\n');
+
+  // Register the marketplace (idempotent: refresh if it was already added).
+  const added = runAgentPluginCli('claude', [
+    'plugin',
+    'marketplace',
+    'add',
+    CLAUDE_MARKETPLACE_ROOT
+  ]);
+  if (added.missing) return { ok: false, missing: true };
+  if (!added.ok) {
+    runAgentPluginCli('claude', ['plugin', 'marketplace', 'update', OVERLORD_MARKETPLACE_NAME]);
+  }
+
+  // Install the plugin (idempotent: update if it was already installed).
+  let installed = runAgentPluginCli('claude', ['plugin', 'install', OVERLORD_PLUGIN_KEY]);
+  if (!installed.ok && !installed.missing) {
+    installed = runAgentPluginCli('claude', ['plugin', 'update', OVERLORD_PLUGIN_KEY]);
+  }
+  return { ok: installed.ok, missing: installed.missing };
+}
+
 function installClaude() {
   const sourceDir = claudeSourcePluginDir();
   const sourceManifest = path.join(sourceDir, '.claude-plugin', 'plugin.json');
@@ -1138,9 +1227,18 @@ function installClaude() {
   } else {
     console.log('  ✓ No v3.25 Claude connector files needed migration.');
   }
-  console.log(
-    '  ✓ `ovld launch claude` now uses the installed Claude local marketplace plugin by default.'
-  );
+
+  const result = installClaudeMarketplacePlugin(sourceDir, sourceVersion);
+  if (result.ok) {
+    console.log(`  ✓ Registered + installed the Claude plugin (${OVERLORD_PLUGIN_KEY}) via the claude CLI.`);
+  } else if (result.missing) {
+    console.log('  ⚠ `claude` CLI not found on PATH — wrote the local marketplace but could not install the plugin.');
+    console.log(
+      `      Run \`claude plugin marketplace add ${CLAUDE_MARKETPLACE_ROOT} && claude plugin install ${OVERLORD_PLUGIN_KEY}\` once Claude Code is installed.`
+    );
+  } else {
+    console.log('  ⚠ Could not install the Claude plugin via the claude CLI. The local marketplace was written; rerun `ovld setup claude` to retry.');
+  }
 
   const manifest = readManifest();
   manifest.claude = {
@@ -1234,6 +1332,21 @@ function installCodex() {
 
   removeLegacyCodexBundle();
 
+  // Copying the plugin + writing the marketplace only makes the plugin
+  // "available". `codex plugin add` is what actually installs/enables it, so the
+  // skill loads in headless/pod sessions where Overlord Desktop never ran.
+  const codexAdd = runAgentPluginCli('codex', ['plugin', 'add', OVERLORD_PLUGIN_KEY]);
+  if (codexAdd.ok) {
+    console.log(`  ✓ Installed plugin via codex CLI: ${OVERLORD_PLUGIN_KEY}`);
+  } else if (codexAdd.missing) {
+    console.log('  ⚠ `codex` CLI not found on PATH — wrote the marketplace but could not install the plugin.');
+    console.log(`      Run \`codex plugin add ${OVERLORD_PLUGIN_KEY}\` once Codex is installed.`);
+  } else if (/already/i.test(`${codexAdd.stdout}${codexAdd.stderr}`)) {
+    console.log(`  ✓ Codex plugin already installed: ${OVERLORD_PLUGIN_KEY}`);
+  } else {
+    console.log('  ⚠ Could not install the Codex plugin via the codex CLI. The marketplace was written; rerun `ovld setup codex` to retry.');
+  }
+
   const installedFiles = [
     ...listFilesRecursive(CODEX_TARGET_PLUGIN_DIR),
     CODEX_TARGET_MARKETPLACE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2606041130.1",
+  "version": "0.2606041635.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -114,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.11 -->
+<!-- version: 0.5.12 -->
 

package/plugins/claude/skills/overlord-ticket/reference/cli.md

@@ -140,6 +140,29 @@ ovld protocol discover-project --working-directory /path/to/repo
 
 Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
+## Creating Projects
+
+Users and agents can create a project directly from the CLI. By default the current
+working directory is registered as the new project's primary resource in the same
+call (one-step setup); pass `--no-directory` to create a bare project.
+
+```bash
+# Create a project and link the current directory in one step
+ovld protocol create-project --name "Acme Web"
+
+# Link a specific directory
+ovld protocol create-project --name "Acme Web" --directory /path/to/repo
+
+# Create a bare project with no directory
+ovld protocol create-project --name "Acme Web" --no-directory
+```
+
+`ovld create-project` is a friendly top-level alias for `ovld protocol create-project`.
+When a directory is registered the command also writes `.overlord/project.json` so
+future cwd-based resolution finds the project. Pass `--organization-id <id>` to create
+in a specific organization (defaults to your membership); `--color <#rrggbb>` sets the
+project color.
+
 ### Resolving the project ID when you don't have one
 
 When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.

package/plugins/claude/skills/overlord-ticket/reference/devices.md

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags). To create a brand-new project (optionally registering a directory as its primary resource in one step) use `ovld protocol create-project --name "..."`.
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -114,5 +114,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.11 -->
+<!-- version: 0.5.12 -->
 

package/plugins/cursor/skills/overlord-ticket/reference/cli.md

@@ -140,6 +140,29 @@ ovld protocol discover-project --working-directory /path/to/repo
 
 Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
+## Creating Projects
+
+Users and agents can create a project directly from the CLI. By default the current
+working directory is registered as the new project's primary resource in the same
+call (one-step setup); pass `--no-directory` to create a bare project.
+
+```bash
+# Create a project and link the current directory in one step
+ovld protocol create-project --name "Acme Web"
+
+# Link a specific directory
+ovld protocol create-project --name "Acme Web" --directory /path/to/repo
+
+# Create a bare project with no directory
+ovld protocol create-project --name "Acme Web" --no-directory
+```
+
+`ovld create-project` is a friendly top-level alias for `ovld protocol create-project`.
+When a directory is registered the command also writes `.overlord/project.json` so
+future cwd-based resolution finds the project. Pass `--organization-id <id>` to create
+in a specific organization (defaults to your membership); `--color <#rrggbb>` sets the
+project color.
+
 ### Resolving the project ID when you don't have one
 
 When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.

package/plugins/cursor/skills/overlord-ticket/reference/devices.md

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags). To create a brand-new project (optionally registering a directory as its primary resource in one step) use `ovld protocol create-project --name "..."`.
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -856,6 +856,61 @@ const tools = [
     }),
     subcommand: 'update-device'
   },
+  {
+    name: 'create_project',
+    description:
+      'Create a new project. By default the current working directory is registered as the project\'s primary resource in one step; pass no_directory:true for a bare project, or directory_path to link a specific directory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Project name.' },
+        color: { type: 'string', description: 'Optional hex color like #d4d4d8.' },
+        directory_path: {
+          type: 'string',
+          description: 'Absolute path to register as primary; omit to use cwd.'
+        },
+        no_directory: {
+          type: 'boolean',
+          description: 'Create a bare project without registering any directory.'
+        },
+        device_fingerprint: { type: 'string' },
+        label: { type: 'string' },
+        is_primary: { type: 'boolean' },
+        device_hostname: { type: 'string' },
+        device_platform: { type: 'string' },
+        organization_id: { type: 'string' }
+      },
+      required: ['name']
+    },
+    toCliFlags: args => ({
+      name: args.name,
+      ...(typeof args.color === 'string' && args.color.trim().length > 0
+        ? { color: args.color.trim() }
+        : {}),
+      ...(args.no_directory === true || args.no_directory === 'true'
+        ? { directory: 'false' }
+        : typeof args.directory_path === 'string' && args.directory_path.trim().length > 0
+          ? { directory: args.directory_path }
+          : {}),
+      ...(typeof args.device_fingerprint === 'string' && args.device_fingerprint.trim().length > 0
+        ? { 'device-fingerprint': args.device_fingerprint.trim() }
+        : {}),
+      ...(typeof args.label === 'string' ? { label: args.label } : {}),
+      ...(args.is_primary !== undefined
+        ? { 'is-primary': args.is_primary === true || args.is_primary === 'true' }
+        : {}),
+      ...(typeof args.device_hostname === 'string' && args.device_hostname.trim().length > 0
+        ? { 'device-hostname': args.device_hostname }
+        : {}),
+      ...(typeof args.device_platform === 'string' && args.device_platform.trim().length > 0
+        ? { 'device-platform': args.device_platform }
+        : {}),
+      ...(typeof args.organization_id === 'string' && args.organization_id.trim().length > 0
+        ? { 'organization-id': args.organization_id.trim() }
+        : {})
+    }),
+    subcommand: 'create-project'
+  },
   {
     name: 'list_project_resources',
     description:

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -115,5 +115,5 @@ For the `record-change-rationales` command and full payload shape with optional
 - [reference/context.md](reference/context.md) — Shared state, attachments, and large artifact policy
 - [reference/shell-escaping.md](reference/shell-escaping.md) — Heredoc stdin piping for special characters in summaries and payloads
 
-<!-- version: 0.5.11 -->
+<!-- version: 0.5.12 -->
 

package/plugins/overlord/skills/overlord-ticket/reference/cli.md

@@ -140,6 +140,29 @@ ovld protocol discover-project --working-directory /path/to/repo
 
 Use `--project-id` when the project id is already known. Use `--working-directory` to override cwd path matching. If the runtime has an `OVERLORD_DEVICE_FINGERPRINT`, pass `--device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"` so resource-directory matching prefers the current device.
 
+## Creating Projects
+
+Users and agents can create a project directly from the CLI. By default the current
+working directory is registered as the new project's primary resource in the same
+call (one-step setup); pass `--no-directory` to create a bare project.
+
+```bash
+# Create a project and link the current directory in one step
+ovld protocol create-project --name "Acme Web"
+
+# Link a specific directory
+ovld protocol create-project --name "Acme Web" --directory /path/to/repo
+
+# Create a bare project with no directory
+ovld protocol create-project --name "Acme Web" --no-directory
+```
+
+`ovld create-project` is a friendly top-level alias for `ovld protocol create-project`.
+When a directory is registered the command also writes `.overlord/project.json` so
+future cwd-based resolution finds the project. Pass `--organization-id <id>` to create
+in a specific organization (defaults to your membership); `--color <#rrggbb>` sets the
+project color.
+
 ### Resolving the project ID when you don't have one
 
 When you need a project ID for a protocol command and the ticket prompt did not supply one, resolve it in this order.

package/plugins/overlord/skills/overlord-ticket/reference/devices.md

@@ -1,6 +1,6 @@
 # Execution Targets And Checkout Paths
 
-Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags).
+Execution targets are canonical rows keyed by a real `device_fingerprint` when known, or by a placeholder until the target registers. Organization labels, user access, project membership, and project checkout paths live in separate association rows. Persist a fingerprint per machine, upsert via `ovld protocol get-device`, then maintain checkout paths via `list-project-resources`, `add-project-resource`, `update-project-resource`, and `update-device` (`ovld protocol help` lists flags). To create a brand-new project (optionally registering a directory as its primary resource in one step) use `ovld protocol create-project --name "..."`.
 
 ```bash
 ovld protocol get-device --device-fingerprint "$OVERLORD_DEVICE_FINGERPRINT"