agendex-cli 1.1.0 → 1.3.0

package/README.md

@@ -23,6 +23,10 @@ agendex configure              # Select which agents/adapters to index
 agendex start                  # Start daemon (backgrounds itself)
 agendex stop                   # Stop the running daemon
 agendex sync                   # One-shot scan + sync to cloud
+agendex sync --force           # Re-sync all plans, ignoring the local hash cache
+agendex upload <path>          # Upload a single Markdown plan file to the cloud
+agendex upload <path> --agent <name>  # Override the uploaded plan's agent label
+agendex upload <path> --open   # Open the uploaded plan in the browser after upload
 agendex cleanup                # Interactively remove cloud daemons
 agendex cleanup --stale        # Auto-remove all stale daemons
 agendex status                 # Show config state, daemon status, uptime & hostname
@@ -57,6 +61,27 @@ AGENDEX_DEV=1 agendex sync
 
 In dev mode the default OAuth site (when you do not pass `--url` and do not set `AGENDEX_SITE_URL`) points at the local EE app URL used for development.
 
+## Plan Value Filtering
+
+Agendex uses a shared plan-value classifier (`@agendex/shared`) to keep non-plans out of your library and cloud account. The same rules apply to local OSS indexing, `agendex sync`, and the background daemon.
+
+**Locally indexed but hidden** (tagged `lowValue` in plan metadata, excluded from search and list views):
+
+- Empty or whitespace-only content
+- Heading-only markdown with no body
+- Prompt-like one-liners, system context dumps, tool logs, conversation artifacts
+- Execution reports, review output, wrapper titles
+- Code-only or code-dominated markdown without plan structure
+- Content with no recognizable planning signals (unstructured one-liners, generic session dumps)
+
+**Cloud sync behavior:**
+
+- Indexable plans upload normally.
+- Low-value plans are still sent on sync so the cloud can **prune** them: existing cloud copies are deleted and new low-value uploads are skipped.
+- Sync output includes counts such as `N low-value skipped/pruned (M deleted)` when pruning runs.
+
+Low-value tagging happens during scan/rescan. If you edit a file into a real plan, the next scan clears the tag and sync uploads it again. Version restore in the cloud rejects low-value snapshots; browse history on a hidden plan to find and restore a good snapshot.
+
 ## Sync Provenance
 
 `agendex sync` and the daemon include sync provenance in cloud payload metadata so the web app can show where a plan was synced from. This includes the device ID, hostname, and the host machine's local IP address when one is available.
@@ -67,6 +92,28 @@ You can disable local IP address collection from Account settings in the cloud a
 AGENDEX_DISABLE_LOCAL_IP=1 agendex sync
 ```
 
+## Real-Time Cloud Sync (Daemon)
+
+While `agendex start` is running, the daemon watches local plan sources and uploads changes to your cloud account. The cloud web app updates reactively once uploads land (no manual refresh).
+
+**How uploads are scheduled:**
+
+1. File watchers (plus periodic rescans) trigger a local rescan when plans change.
+2. Each changed plan is converted to a sync payload and enqueued. The queue **deduplicates by plan id** (last write wins).
+3. **`sync-cache.json`** stores content hashes so unchanged plans are skipped (same as one-shot sync). Use `agendex sync --force` to bypass the cache for a manual full upload.
+4. Before each upload, the daemon re-checks that the queued payload is still the latest edit for that plan (so a slow retry cannot overwrite a newer change).
+5. Failed uploads retry automatically with exponential backoff (**2s → 8s → 30s**, up to three attempts) before the daemon logs a permanent failure.
+
+Low-value plans follow the same queue and pruning rules as [Plan Value Filtering](#plan-value-filtering).
+
+| Variable                              | Default  | Purpose                                                                                                    |
+| ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `AGENDEX_LIVE_SESSION_POLL_MS`        | `2000`   | Poll active Plannotator live sessions (re-fetch loopback plan content). Set to `0` to disable.             |
+| `AGENDEX_SYNC_RESCAN_INTERVAL_MS`     | `60000`  | Safety-net full rescan + hash-diff upload when `fs.watch` misses an event. Set to `0` to disable.          |
+| `AGENDEX_WATCHER_REFRESH_INTERVAL_MS` | `300000` | Re-discover watch directories (new Cursor projects, `@plans` folders, custom dirs). Set to `0` to disable. |
+
+Typical latency after a local edit: **~0.5–2s** for file-based agents (Cursor, Claude Code, markdown snapshots); **~2–3s** for Plannotator live-session-only edits (loopback poll).
+
 ## Daemon Cleanup
 
 `agendex cleanup` manages registered daemon devices in the cloud.

package/dist/cli.js

@@ -1059,8 +1059,8 @@ var init_cleanup = __esm(() => {
 
 // src/cli.ts
 import { spawn as spawn4 } from "node:child_process";
-import { existsSync as existsSync12, statSync as statSync2, writeSync } from "node:fs";
-import { resolve as resolve9 } from "node:path";
+import { existsSync as existsSync13, statSync as statSync2, writeSync } from "node:fs";
+import { resolve as resolve10 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // ../shared/src/adapters/catalog.ts
@@ -2822,6 +2822,7 @@ function normalizeStoredConfig(raw) {
   const token = typeof raw.token === "string" && raw.token.trim() ? raw.token : undefined;
   const cloudToken = typeof raw.cloudToken === "string" && raw.cloudToken.trim() ? raw.cloudToken : undefined;
   const convexUrl = typeof raw.convexUrl === "string" && raw.convexUrl.trim() ? raw.convexUrl : undefined;
+  const siteUrl = typeof raw.siteUrl === "string" && raw.siteUrl.trim() ? raw.siteUrl : undefined;
   const deviceId = typeof raw.deviceId === "string" && raw.deviceId.trim() ? raw.deviceId : undefined;
   const collectLocalIpAddress = typeof raw.collectLocalIpAddress === "boolean" ? raw.collectLocalIpAddress : undefined;
   return {
@@ -2829,6 +2830,7 @@ function normalizeStoredConfig(raw) {
     token,
     cloudToken,
     convexUrl,
+    siteUrl,
     deviceId,
     collectLocalIpAddress,
     enabledAdapters: normalizeAdapterIds(raw.enabledAdapters),
@@ -2845,6 +2847,7 @@ function saveConfig(config) {
     token: config.token,
     cloudToken: config.cloudToken,
     convexUrl: config.convexUrl,
+    siteUrl: config.siteUrl,
     deviceId: config.deviceId,
     collectLocalIpAddress: config.collectLocalIpAddress,
     enabledAdapters: sanitizeEnabledAdapterIds(config.enabledAdapters),
@@ -2923,6 +2926,7 @@ async function loadOrInitConfig(options = {}) {
     token: tokenFromEnv ? existing?.token : currentToken,
     cloudToken: existing?.cloudToken,
     convexUrl: existing?.convexUrl,
+    siteUrl: existing?.siteUrl,
     deviceId,
     enabledAdapters,
     customPlanDirs: existing?.customPlanDirs ?? []
@@ -2954,6 +2958,7 @@ function isIndexablePlan(plan) {
 }
 var PROPOSED_PLAN_TAG_REGEX2 = /<\s*\/?\s*proposed_plan\s*>/gi;
 var ESCAPED_PROPOSED_PLAN_TAG_REGEX2 = /&lt;\s*\/?\s*proposed_plan\s*&gt;/gi;
+var FENCED_CODE_BLOCK_REGEX = /(?:```|~~~)[\s\S]*?(?:```|~~~)/g;
 var VISIBLE_TEXT_REGEX = /[\p{L}\p{N}]/u;
 var LOW_VALUE_METADATA_KEYS = ["lowValue", "lowValueReasons", "lowValueSignals"];
 function normalizeLineEndings2(text) {
@@ -2973,7 +2978,7 @@ function normalizePlanContent(content) {
   return stripBoundaryHtmlComments(normalizeLineEndings2(content).replace(/^\uFEFF/, "").replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "").replace(ESCAPED_PROPOSED_PLAN_TAG_REGEX2, "").replace(PROPOSED_PLAN_TAG_REGEX2, "")).trim();
 }
 function withoutLowValueMetadata(metadata) {
-  const next = { ...metadata ?? {} };
+  const next = { ...metadata };
   for (const key of LOW_VALUE_METADATA_KEYS)
     delete next[key];
   return next;
@@ -2984,6 +2989,23 @@ function unique(items) {
 function visibleText(text) {
   return text.replace(/<!--[\s\S]*?-->/g, "").replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "").replace(ESCAPED_PROPOSED_PLAN_TAG_REGEX2, "").replace(PROPOSED_PLAN_TAG_REGEX2, "").replace(/[`*_#[\](){}<>:|~\-+=.]/g, " ").trim();
 }
+function stripFencedCodeBlocks(text) {
+  return text.replace(FENCED_CODE_BLOCK_REGEX, " ");
+}
+function wordCount(text) {
+  return text.match(/[\p{L}\p{N}_]+/gu)?.length ?? 0;
+}
+function codeBlockMetrics(text) {
+  const blocks = text.match(FENCED_CODE_BLOCK_REGEX) ?? [];
+  const codeCharCount = blocks.reduce((sum, block) => sum + block.length, 0);
+  const nonCode = stripFencedCodeBlocks(text);
+  return {
+    codeBlockCount: blocks.length,
+    codeCharCount,
+    codeShare: codeCharCount / Math.max(text.length, 1),
+    nonCodeWordCount: wordCount(visibleText(nonCode))
+  };
+}
 function isSeparatorLine(line) {
   return /^(?:-{3,}|_{3,}|\*{3,})$/.test(line.trim());
 }
@@ -3007,7 +3029,7 @@ function isOrderedListLine(line) {
   return /^\d+[.)]\s+\S/.test(line.trim());
 }
 function isHeadingOnly(lines) {
-  return lines.length > 0 && lines.some(isHeadingLine) && lines.every(isHeadingLine);
+  return lines.some(isHeadingLine) && lines.every(isHeadingLine);
 }
 function metadataHasPlanBlocks(metadata) {
   const planBlocks = metadata?.planBlocks;
@@ -3108,13 +3130,20 @@ function collectPositiveSignals(normalized, lines, metadata) {
   }).length;
   if (actionBulletCount >= 2)
     signals.push("action-bullets");
-  if (lines.length >= 2 && /\b(?:will|should|need to|needs to|plan to|planned|approach is to|implementation will)\b/i.test(normalized)) {
+  const nonCodeVisible = visibleText(stripFencedCodeBlocks(normalized));
+  if (lines.length >= 2 && /\b(?:will|should|need to|needs to|plan to|planned|approach is to|implementation will)\b/i.test(nonCodeVisible)) {
     signals.push("future-plan-language");
   }
+  const planningPhraseCount = nonCodeVisible.match(/\b(?:will|should|need to|needs to|plan to|approach|implementation|implement|add|update|modify|create|remove|refactor|test|verify|validate|steps?|tasks?)\b/gi)?.length ?? 0;
+  const proseWordCount = wordCount(nonCodeVisible);
+  const isPlanningProse = proseWordCount >= 35 && planningPhraseCount >= 4 || proseWordCount >= 3 && planningPhraseCount >= 3 && planningPhraseCount / proseWordCount >= 0.4;
+  if (isPlanningProse) {
+    signals.push("planning-prose");
+  }
   return unique(signals);
 }
 function isStrongPositiveSignal(signal) {
-  return signal === "metadata:proposed-plan-block" || signal === "checklist" || signal === "ordered-steps" || signal === "action-bullets" || signal === "section:approach" || signal === "section:implementation-plan" || signal === "section:files-to-modify" || signal === "section:steps" || signal === "section:acceptance-criteria";
+  return signal === "metadata:proposed-plan-block" || signal === "checklist" || signal === "ordered-steps" || signal === "action-bullets" || signal === "planning-prose" || signal === "section:approach" || signal === "section:implementation-plan" || signal === "section:files-to-modify" || signal === "section:steps" || signal === "section:acceptance-criteria";
 }
 function hasStrongPlanSignal(positiveSignals) {
   const sectionCount = positiveSignals.filter((signal) => signal.startsWith("section:")).length;
@@ -3177,6 +3206,13 @@ function looksLikeSystemContext(normalized, lines) {
 function looksLikeToolLog(normalized) {
   return /::[a-z0-9_-]+(?:\{|\[|\s*$)/i.test(normalized) || /<\/?(?:tool_call|tool_result)\b[^>]*>/i.test(normalized) || /\b(?:function_call|tool_calls|tool_result)\b/i.test(normalized);
 }
+function looksLikeConversationArtifact(lines) {
+  const roleLineCount = lines.filter((line) => /^(?:[-*+]\s+)?(?:\*\*)?(?:user|assistant|system|developer|tool|agent)(?:\*\*)?\s*:/i.test(line.trim())).length;
+  if (roleLineCount >= 2)
+    return true;
+  const wrapperCount = lines.filter((line) => /^<\/?(?:user_action|user_prompt|assistant_response|message|conversation)\b/i.test(line.trim())).length;
+  return wrapperCount >= 2;
+}
 function looksLikeExecutionReport(normalized) {
   const hasPastCompletion = /\b(?:fixed|pushed|committed|completed|done|implemented|updated|changed|patched|merged|deployed|passed|failed|resolved|reverted)\b/i.test(normalized);
   const hasReportSection = /^\s*(?:summary|result|results|changes|verification|status)\s*:/im.test(normalized);
@@ -3208,14 +3244,20 @@ function assessPlanValue(input) {
   const strongPositive = hasStrongPlanSignal(positiveSignals);
   const systemContext = looksLikeSystemContext(normalized, lines);
   const toolLog = looksLikeToolLog(normalized);
+  const conversationArtifact = looksLikeConversationArtifact(lines);
   const executionReport = looksLikeExecutionReport(normalized);
   const wrapperTitle = looksLikeWrapperTitle(input.title);
   const promptTitle = looksLikePromptTitle(input.title);
   const reviewOutput = looksLikeReviewOutput(normalized, input.title);
+  const codeMetrics = codeBlockMetrics(normalized);
+  const codeOnly = codeMetrics.codeBlockCount > 0 && codeMetrics.nonCodeWordCount === 0;
+  const codeDominated = codeMetrics.codeBlockCount > 0 && codeMetrics.codeShare >= 0.6 && codeMetrics.nonCodeWordCount < 120;
   if (systemContext)
     signals.push("negative:system-context");
   if (toolLog)
     signals.push("negative:tool-log");
+  if (conversationArtifact)
+    signals.push("negative:conversation-artifact");
   if (executionReport)
     signals.push("negative:execution-report");
   if (wrapperTitle)
@@ -3224,24 +3266,36 @@ function assessPlanValue(input) {
     signals.push("negative:prompt-title");
   if (reviewOutput)
     signals.push("negative:review-output");
+  if (codeMetrics.codeBlockCount > 0)
+    signals.push("shape:code-blocks");
+  if (codeOnly)
+    signals.push("negative:code-only");
+  if (codeDominated)
+    signals.push("negative:code-dominated");
   if (lines.length === 1)
     signals.push("shape:single-line");
   if (lines.length === 1 && positiveSignals.length === 0) {
     reasons.push(isPromptLikeOneLiner(lines[0] ?? "") ? "prompt-like" : "no-plan-signals");
   }
-  if (systemContext && !strongPositive)
+  if (systemContext && !explicitPlanBlock)
     reasons.push("system-context");
-  if (executionReport && !strongPositive)
+  if (toolLog && !explicitPlanBlock)
+    reasons.push("tool-log");
+  if (conversationArtifact && !explicitPlanBlock && !strongPositive)
+    reasons.push("conversation-artifact");
+  if (executionReport && !explicitPlanBlock)
     reasons.push("execution-report");
   if (wrapperTitle && !explicitPlanBlock)
     reasons.push("wrapper-title");
   if (reviewOutput && !explicitPlanBlock)
     reasons.push("review-output");
-  if (promptTitle && !strongPositive && positiveSignals.length === 0)
+  if (promptTitle && !strongPositive && !explicitPlanBlock)
     reasons.push("prompt-like");
-  if (toolLog && !strongPositive && positiveSignals.length === 0)
-    reasons.push("no-plan-signals");
-  if (reasons.length === 0 && positiveSignals.length === 0 && lines.length <= 3) {
+  if (codeOnly && !explicitPlanBlock && !strongPositive)
+    reasons.push("code-only");
+  if (codeDominated && !explicitPlanBlock && !strongPositive)
+    reasons.push("code-dominated");
+  if (reasons.length === 0 && !strongPositive && !positiveSignals.includes("planning-prose")) {
     reasons.push("no-plan-signals");
   }
   return lowValueAssessment(reasons, signals);
@@ -3422,6 +3476,9 @@ async function walkDir(dir, depth = 0, seen = new Set) {
   } catch {}
   return files;
 }
+function preparePlanForIndex(plan) {
+  return annotatePlanValueMetadata(plan);
+}
 async function parseGenericMarkdownPlan(filePath, extraMetadata) {
   try {
     const content = await readFile7(filePath, "utf-8");
@@ -3461,7 +3518,7 @@ async function scanUserPlans(into) {
       continue;
     const plan = await parseGenericMarkdownPlan(file, { userCreated: true });
     if (plan)
-      into.set(plan.id, plan);
+      into.set(plan.id, preparePlanForIndex(plan));
   }
 }
 function getCustomPlanDirs() {
@@ -3523,7 +3580,7 @@ async function scanCustomPlanDirs(coveredPaths, into) {
         agentHint: dirBasename
       });
       if (plan) {
-        into.set(plan.id, plan);
+        into.set(plan.id, preparePlanForIndex(plan));
         count++;
       }
     }
@@ -3543,7 +3600,7 @@ async function scan() {
           continue;
         const plans = await adapter.parse(file);
         for (const plan of plans) {
-          const annotated = annotatePlanValueMetadata(plan);
+          const annotated = preparePlanForIndex(plan);
           next.set(annotated.id, annotated);
         }
       }
@@ -3563,7 +3620,7 @@ async function scan() {
         continue;
       const plans = await adapter.parse(file);
       for (const plan of plans) {
-        const annotated = annotatePlanValueMetadata(plan);
+        const annotated = preparePlanForIndex(plan);
         next.set(annotated.id, annotated);
       }
     }
@@ -3660,7 +3717,7 @@ async function rescanFile(filePath) {
       removedPlans.push(...removePlansForPath(filePath, adapter));
       continue;
     }
-    const plans = rawPlans.map(annotatePlanValueMetadata);
+    const plans = rawPlans.map(preparePlanForIndex);
     for (const plan of plans) {
       store.set(plan.id, plan);
     }
@@ -3673,9 +3730,10 @@ async function rescanFile(filePath) {
   if (normalized.endsWith(".md") && (normalized.startsWith(userPlansDir + sep3) || normalized === userPlansDir)) {
     const plan = await parseGenericMarkdownPlan(filePath, { userCreated: true });
     if (plan) {
-      store.set(plan.id, plan);
+      const annotated = preparePlanForIndex(plan);
+      store.set(annotated.id, annotated);
       notifyPlansChanged();
-      return [plan];
+      return [annotated];
     }
   }
   if (normalized.endsWith(".md")) {
@@ -3688,9 +3746,10 @@ async function rescanFile(filePath) {
           customDir: dir
         });
         if (plan) {
-          store.set(plan.id, plan);
+          const annotated = preparePlanForIndex(plan);
+          store.set(annotated.id, annotated);
           notifyPlansChanged();
-          return [plan];
+          return [annotated];
         }
       }
     }
@@ -3751,6 +3810,38 @@ function startWatching(onChange) {
 function stopWatching() {
   closeAllWatchers();
 }
+function collectWatchPaths() {
+  const adapters = getActiveAdapters();
+  const watchedPaths = new Set;
+  for (const adapter of adapters) {
+    for (const watchPath of adapter.getWatchPaths()) {
+      watchedPaths.add(resolve5(watchPath));
+    }
+  }
+  const discovered = discoverProjectPlanDirs();
+  for (const { dir, agent } of discovered) {
+    if (watchedPaths.has(resolve5(dir)))
+      continue;
+    const adapter = adapters.find((a) => a.agent === agent);
+    if (!adapter)
+      continue;
+    watchedPaths.add(resolve5(dir));
+  }
+  for (const dir of getCustomPlanDirs()) {
+    const resolvedCustom = resolve5(dir);
+    let overlaps = false;
+    for (const watched of watchedPaths) {
+      if (pathsOverlapFilesystemTree(resolvedCustom, watched)) {
+        overlaps = true;
+        break;
+      }
+    }
+    if (overlaps)
+      continue;
+    watchedPaths.add(resolvedCustom);
+  }
+  return [...watchedPaths].sort();
+}
 function setupWatchers(onChange) {
   const adapters = getActiveAdapters();
   const watchedPaths = new Set;
@@ -3870,7 +3961,8 @@ function parseSyncSuccess(body) {
     return {
       ok: true,
       skippedLowValue: result.skippedLowValue === true,
-      deleted: result.deleted === true
+      deleted: result.deleted === true,
+      ...typeof result.planId === "string" && { planId: result.planId }
     };
   } catch {
     return { ok: true };
@@ -3905,7 +3997,7 @@ async function syncPlan(plan) {
     }
   }
   if (res.status < 200 || res.status >= 300) {
-    return { ok: false, error: `${res.status}: ${res.body}` };
+    return { ok: false, status: res.status, error: `${res.status}: ${res.body}` };
   }
   return parseSyncSuccess(res.body);
 }
@@ -4191,6 +4283,12 @@ function getDefaultSiteUrl() {
     return process.env.AGENDEX_SITE_URL;
   return isDevMode() ? DEV_SITE_URL : PROD_SITE_URL;
 }
+function getSiteUrl() {
+  const config = loadConfig();
+  if (config?.siteUrl)
+    return config.siteUrl;
+  return getDefaultSiteUrl();
+}
 function launchBrowser(url, label) {
   console.log(`[agendex] Opening ${label}...`);
   console.log(`[agendex] If it doesn't open, visit: ${url}`);
@@ -4203,15 +4301,16 @@ function launchBrowser(url, label) {
 async function login(siteUrlOverride) {
   const { port, result } = await startCallbackServer();
   const callbackUrl = `http://127.0.0.1:${port}/callback`;
-  const siteUrl = siteUrlOverride ?? getDefaultSiteUrl();
+  const existing = loadConfig();
+  const siteUrl = siteUrlOverride ?? existing?.siteUrl ?? getDefaultSiteUrl();
   const authUrl = `${siteUrl}/auth/cli?callback=${encodeURIComponent(callbackUrl)}`;
   launchBrowser(authUrl, "browser for authentication");
   const callback = await result;
-  const existing = loadConfig();
   const config = {
     configVersion: 3,
     cloudToken: callback.token,
     convexUrl: callback.convexUrl,
+    siteUrl,
     enabledAdapters: existing?.enabledAdapters ?? [],
     customPlanDirs: existing?.customPlanDirs ?? [],
     ...existing?.token ? { token: existing.token } : {},
@@ -4232,7 +4331,8 @@ function logout() {
     enabledAdapters: existing.enabledAdapters,
     customPlanDirs: existing.customPlanDirs,
     ...existing.token ? { token: existing.token } : {},
-    ...existing.deviceId ? { deviceId: existing.deviceId } : {}
+    ...existing.deviceId ? { deviceId: existing.deviceId } : {},
+    ...existing.siteUrl ? { siteUrl: existing.siteUrl } : {}
   };
   saveConfig(config);
   console.log("[agendex] Logged out. Cloud token removed.");
@@ -4376,7 +4476,7 @@ function spawnBrowser(command, args, options = {}) {
 // src/daemon.ts
 import { spawn as spawn2 } from "node:child_process";
 import { hostname as osHostname2 } from "node:os";
-import { resolve as resolve6 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/adapters.ts
@@ -4405,6 +4505,86 @@ function resolveCliAdapterIds(config) {
   return ids;
 }
 
+// src/sync-cache.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join12 } from "node:path";
+function getCachePath() {
+  return join12(getConfigDir(), "sync-cache.json");
+}
+function loadSyncCache() {
+  const cachePath = getCachePath();
+  if (!existsSync8(cachePath))
+    return {};
+  try {
+    const raw = JSON.parse(readFileSync5(cachePath, "utf-8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+      return {};
+    return raw;
+  } catch {
+    return {};
+  }
+}
+function saveSyncCache(cache, options) {
+  const dir = getConfigDir();
+  if (!existsSync8(dir))
+    mkdirSync3(dir, { recursive: true });
+  const cachePath = getCachePath();
+  if (options?.replace) {
+    writeFileSync3(cachePath, JSON.stringify(cache));
+    return;
+  }
+  const existing = loadSyncCache();
+  writeFileSync3(cachePath, JSON.stringify({ ...existing, ...cache }));
+}
+function computePayloadHash(payload) {
+  const canonical = JSON.stringify([
+    payload.localPlanId,
+    payload.agent,
+    payload.title,
+    payload.content,
+    payload.format,
+    payload.filePath ?? null,
+    payload.workspace ?? null,
+    payload.metadata ?? null,
+    payload.createdAt ?? null,
+    payload.updatedAt ?? null
+  ]);
+  return createHash2("sha256").update(canonical).digest("hex").slice(0, 20);
+}
+
+// src/daemon-sync.ts
+var DEFAULT_LIVE_SESSION_POLL_MS = 2000;
+var DEFAULT_SYNC_RESCAN_INTERVAL_MS = 60000;
+var DEFAULT_WATCHER_REFRESH_INTERVAL_MS = 300000;
+var SYNC_RETRY_DELAYS_MS = [2000, 8000, 30000];
+var SYNC_MAX_RETRIES = SYNC_RETRY_DELAYS_MS.length;
+function parseEnvMs(name, defaultMs) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "")
+    return defaultMs;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return defaultMs;
+  return parsed;
+}
+function dedupeSyncPayloads(payloads) {
+  const byId = new Map;
+  for (const payload of payloads) {
+    byId.set(payload.localPlanId, payload);
+  }
+  return [...byId.values()];
+}
+function payloadNeedsSync(payload, cache) {
+  return cache[payload.localPlanId] !== computePayloadHash(payload);
+}
+function filterPayloadsNeedingSync(payloads, cache) {
+  return payloads.filter((payload) => payloadNeedsSync(payload, cache));
+}
+function nextRetryDelayMs(attempt) {
+  return SYNC_RETRY_DELAYS_MS[attempt];
+}
+
 // src/network.ts
 import { execFileSync } from "node:child_process";
 import { networkInterfaces } from "node:os";
@@ -4521,6 +4701,7 @@ function isIpv4Address(address) {
 }
 
 // src/payload.ts
+import { basename as basename6, resolve as resolve6 } from "node:path";
 var SYNC_METADATA_KEY = "agendexSync";
 function isRecord4(value) {
   return typeof value === "object" && value !== null;
@@ -4539,6 +4720,36 @@ function withSyncDeviceMetadata(metadata, deviceId, hostname2, ipAddress) {
     }
   };
 }
+function parseUploadFile(filePath, content, agentOverride) {
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  const override = agentOverride?.trim();
+  let agent = override || "uploaded";
+  if (!override && fmMatch) {
+    const agentLine = fmMatch[1]?.match(/^agent:\s*(.+)$/m);
+    if (agentLine?.[1])
+      agent = agentLine[1].trim();
+  }
+  const body = fmMatch ? content.slice(fmMatch[0].length) : content;
+  const titleMatch = body.match(/^#\s+(.+)/m);
+  const title = titleMatch?.[1]?.trim() || basename6(filePath).replace(/\.md$/i, "") || "Untitled";
+  return { title, agent, body };
+}
+function fileToSyncPayload(filePath, content, options = {}) {
+  const absolutePath = resolve6(filePath);
+  const { title, agent, body } = parseUploadFile(absolutePath, content, options.agentOverride);
+  const now = Date.now();
+  return {
+    localPlanId: hashPath(absolutePath),
+    agent,
+    title,
+    content: body,
+    format: "md",
+    filePath: absolutePath,
+    metadata: withSyncDeviceMetadata({ uploaded: true, userCreated: true }, options.deviceId, options.hostname, options.ipAddress),
+    createdAt: options.createdAt ?? now,
+    updatedAt: options.updatedAt ?? now
+  };
+}
 function planToSyncPayload(plan, deviceId, hostname2, ipAddress) {
   return {
     localPlanId: plan.id,
@@ -4554,54 +4765,6 @@ function planToSyncPayload(plan, deviceId, hostname2, ipAddress) {
   };
 }
 
-// src/sync-cache.ts
-import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "node:fs";
-import { join as join12 } from "node:path";
-function getCachePath() {
-  return join12(getConfigDir(), "sync-cache.json");
-}
-function loadSyncCache() {
-  const cachePath = getCachePath();
-  if (!existsSync8(cachePath))
-    return {};
-  try {
-    const raw = JSON.parse(readFileSync5(cachePath, "utf-8"));
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-      return {};
-    return raw;
-  } catch {
-    return {};
-  }
-}
-function saveSyncCache(cache, options) {
-  const dir = getConfigDir();
-  if (!existsSync8(dir))
-    mkdirSync3(dir, { recursive: true });
-  const cachePath = getCachePath();
-  if (options?.replace) {
-    writeFileSync3(cachePath, JSON.stringify(cache));
-    return;
-  }
-  const existing = loadSyncCache();
-  writeFileSync3(cachePath, JSON.stringify({ ...existing, ...cache }));
-}
-function computePayloadHash(payload) {
-  const canonical = JSON.stringify([
-    payload.localPlanId,
-    payload.agent,
-    payload.title,
-    payload.content,
-    payload.format,
-    payload.filePath ?? null,
-    payload.workspace ?? null,
-    payload.metadata ?? null,
-    payload.createdAt ?? null,
-    payload.updatedAt ?? null
-  ]);
-  return createHash2("sha256").update(canonical).digest("hex").slice(0, 20);
-}
-
 // src/sync-privacy.ts
 async function shouldIncludeLocalIpAddressInSync() {
   if (!shouldCollectLocalIpAddress())
@@ -4668,6 +4831,10 @@ var PLANNOTATOR_WRITEBACK_POLL_INTERVAL_MS = 15000;
 var PLANNOTATOR_WRITEBACK_EXPIRED_ERROR = "Write-back expired before delivery.";
 var PLANNOTATOR_WRITEBACK_FAILED_ERROR = "No live Plannotator session accepted the write-back payload.";
 var PLANNOTATOR_LIVENESS_SWEEP_INTERVAL_MS = 20000;
+var LIVE_SESSION_POLL_MS = parseEnvMs("AGENDEX_LIVE_SESSION_POLL_MS", DEFAULT_LIVE_SESSION_POLL_MS);
+var SYNC_RESCAN_INTERVAL_MS = parseEnvMs("AGENDEX_SYNC_RESCAN_INTERVAL_MS", DEFAULT_SYNC_RESCAN_INTERVAL_MS);
+var WATCHER_REFRESH_INTERVAL_MS = parseEnvMs("AGENDEX_WATCHER_REFRESH_INTERVAL_MS", DEFAULT_WATCHER_REFRESH_INTERVAL_MS);
+var RETRY_TICK_INTERVAL_MS = 1000;
 function isRecord5(value) {
   return typeof value === "object" && value !== null;
 }
@@ -4701,6 +4868,9 @@ async function runWorker() {
   setActiveAdapters(adapters);
   const syncCache = loadSyncCache();
   const syncQueue = [];
+  const retryQueue = [];
+  const retryAttemptByPlanId = new Map;
+  const lastSyncedUpdatedAt = new Map;
   const pendingWritebackReports = loadPendingWritebackReports();
   const liveSessions = new Map;
   let syncing = false;
@@ -4726,17 +4896,76 @@ async function runWorker() {
     console.log("[agendex] cloud token refreshed");
     return true;
   }
+  function pushToSyncQueue(...payloads) {
+    for (const payload of payloads) {
+      const idx = syncQueue.findIndex((p) => p.localPlanId === payload.localPlanId);
+      if (idx >= 0) {
+        const existing = syncQueue[idx];
+        if (existing?.updatedAt !== undefined && payload.updatedAt !== undefined && existing.updatedAt >= payload.updatedAt) {
+          continue;
+        }
+        syncQueue[idx] = payload;
+      } else {
+        syncQueue.push(payload);
+      }
+    }
+  }
+  function scheduleSyncRetry(payload, attempt) {
+    const delayMs = nextRetryDelayMs(attempt);
+    if (delayMs === undefined) {
+      console.error(`[agendex] sync gave up for "${payload.title}" after ${SYNC_MAX_RETRIES} attempts`);
+      return;
+    }
+    retryQueue.push({ payload, attempt: attempt + 1, retryAt: Date.now() + delayMs });
+  }
+  function flushReadyRetries() {
+    const now = Date.now();
+    let moved = 0;
+    for (let i = retryQueue.length - 1;i >= 0; i--) {
+      const entry = retryQueue[i];
+      if (!entry || entry.retryAt > now)
+        continue;
+      retryQueue.splice(i, 1);
+      const lastSynced = lastSyncedUpdatedAt.get(entry.payload.localPlanId);
+      if (lastSynced !== undefined && entry.payload.updatedAt !== undefined && lastSynced >= entry.payload.updatedAt) {
+        continue;
+      }
+      pushToSyncQueue(entry.payload);
+      retryAttemptByPlanId.set(entry.payload.localPlanId, entry.attempt);
+      moved++;
+    }
+    if (moved > 0)
+      processSyncQueue();
+  }
+  async function enqueueChangedPlans(plans2) {
+    if (plans2.length === 0)
+      return 0;
+    const ipAddress = await getSyncIpAddress();
+    const payloads = plans2.map((plan) => planToSyncPayload(plan, config.deviceId, hostname2, ipAddress));
+    const needingSync = filterPayloadsNeedingSync(payloads, syncCache);
+    if (needingSync.length === 0)
+      return 0;
+    pushToSyncQueue(...needingSync);
+    processSyncQueue();
+    return needingSync.length;
+  }
   async function processSyncQueue() {
     if (syncing || syncQueue.length === 0)
       return;
     syncing = true;
-    const batch = syncQueue.splice(0);
+    const batch = dedupeSyncPayloads(syncQueue.splice(0));
     let syncedCount = 0;
     let lowValueSkippedCount = 0;
     let lowValueDeletedCount = 0;
     let failedCount = 0;
+    const failedPayloads = [];
     try {
       for (const payload of batch) {
+        const lastSynced = lastSyncedUpdatedAt.get(payload.localPlanId);
+        if (lastSynced !== undefined && payload.updatedAt !== undefined && lastSynced >= payload.updatedAt) {
+          retryAttemptByPlanId.delete(payload.localPlanId);
+          continue;
+        }
         let result = await syncPlan(payload);
         if (!result.ok && result.error?.includes("401")) {
           const refreshed = await tryRefreshToken();
@@ -4747,11 +4976,12 @@ async function runWorker() {
         if (!result.ok) {
           if (result.error?.includes("401")) {
             console.error("[agendex] session expired. Run `agendex login` to re-authenticate.");
-            batch.length = 0;
             syncQueue.length = 0;
+            retryQueue.length = 0;
             break;
           }
           failedCount++;
+          failedPayloads.push(payload);
           console.error(`[agendex] sync failed for "${payload.title}": ${result.error}`);
         } else {
           if (result.skippedLowValue) {
@@ -4762,14 +4992,23 @@ async function runWorker() {
             syncedCount++;
           }
           syncCache[payload.localPlanId] = computePayloadHash(payload);
+          retryAttemptByPlanId.delete(payload.localPlanId);
+          if (payload.updatedAt !== undefined) {
+            lastSyncedUpdatedAt.set(payload.localPlanId, payload.updatedAt);
+          }
         }
       }
     } catch (err) {
       console.error("[agendex] sync error:", err);
-      syncQueue.unshift(...batch.slice(syncedCount + lowValueSkippedCount + failedCount));
+      pushToSyncQueue(...batch.slice(syncedCount + lowValueSkippedCount + failedCount));
     } finally {
       syncing = false;
     }
+    for (const payload of failedPayloads) {
+      const attempt = retryAttemptByPlanId.get(payload.localPlanId) ?? 0;
+      retryAttemptByPlanId.delete(payload.localPlanId);
+      scheduleSyncRetry(payload, attempt);
+    }
     if (syncedCount > 0 || lowValueSkippedCount > 0 || failedCount > 0) {
       saveSyncCache(syncCache);
       const lowValueSuffix2 = lowValueSkippedCount > 0 ? `, ${lowValueSkippedCount} low-value skipped/pruned${lowValueDeletedCount > 0 ? ` (${lowValueDeletedCount} deleted)` : ""}` : "";
@@ -4791,7 +5030,7 @@ async function runWorker() {
       if (livePayloads.has(planId))
         continue;
       const endedPayload = buildEndedPlannotatorPayload(lastPayload);
-      syncQueue.push(endedPayload);
+      pushToSyncQueue(endedPayload);
       liveSessions.delete(planId);
       queued = true;
       console.log(`[agendex] Plannotator session ended: ${endedPayload.title}`);
@@ -4857,7 +5096,7 @@ async function runWorker() {
       const updatedPlan = getById(job.localPlanId);
       if (updatedPlan) {
         const updatedPayload = planToSyncPayload(updatedPlan, config.deviceId, hostname2, await getSyncIpAddress());
-        syncQueue.push(updatedPayload);
+        pushToSyncQueue(updatedPayload);
         if (isLivePlannotatorPayload(updatedPayload)) {
           liveSessions.set(updatedPayload.localPlanId, updatedPayload);
         }
@@ -4892,7 +5131,15 @@ async function runWorker() {
       pollingWritebacks = false;
     }
   }
-  setOnPlansChanged(() => {});
+  let lastWatchPathKey = collectWatchPaths().join("\x00");
+  const onPlansFileChange = (changedPlans) => {
+    (async () => {
+      await enqueueChangedPlans(changedPlans);
+      await reconcileLivePlannotatorSessions(getAll());
+    })().catch((err) => {
+      console.error("[agendex] failed to queue changed plans:", err);
+    });
+  };
   console.log(`[agendex] initial scan...`);
   await scan();
   const plans = getAll();
@@ -4904,8 +5151,7 @@ async function runWorker() {
   const initialIpAddress = await getSyncIpAddress();
   for (const plan of plans) {
     const payload = planToSyncPayload(plan, config.deviceId, hostname2, initialIpAddress);
-    const hash = computePayloadHash(payload);
-    if (syncCache[plan.id] === hash) {
+    if (syncCache[plan.id] === computePayloadHash(payload)) {
       initialSkipped++;
       continue;
     }
@@ -4914,7 +5160,7 @@ async function runWorker() {
     } else {
       initialQueuedSyncable++;
     }
-    syncQueue.push(payload);
+    pushToSyncQueue(payload);
   }
   const activePlanIds = new Set(plans.map((plan) => plan.id));
   for (const id of Object.keys(syncCache)) {
@@ -4926,35 +5172,75 @@ async function runWorker() {
   console.log(`[agendex] syncing ${initialQueuedSyncable} plans${lowValueSuffix} (${initialQueuedLowValue} low-value queued, ${initialSkipped} unchanged)...`);
   await processSyncQueue();
   await reconcileLivePlannotatorSessions(getAll());
+  setOnPlansChanged((plans2) => {
+    enqueueChangedPlans(plans2).catch((err) => {
+      console.error("[agendex] failed to sync plan store changes:", err);
+    });
+  });
   setInterval(() => {
     (async () => {
       await sendHeartbeat(await getSyncIpAddress());
     })().catch(() => {});
   }, CLI_DAEMON_HEARTBEAT_INTERVAL_MS);
+  setInterval(() => {
+    flushReadyRetries();
+  }, RETRY_TICK_INTERVAL_MS);
+  if (SYNC_RESCAN_INTERVAL_MS > 0) {
+    setInterval(() => {
+      (async () => {
+        await scan();
+        await enqueueChangedPlans(getAll());
+        await reconcileLivePlannotatorSessions(getAll());
+      })().catch((err) => {
+        console.error("[agendex] safety rescan failed:", err);
+      });
+    }, SYNC_RESCAN_INTERVAL_MS);
+  }
+  if (WATCHER_REFRESH_INTERVAL_MS > 0) {
+    setInterval(() => {
+      const nextKey = collectWatchPaths().join("\x00");
+      if (nextKey === lastWatchPathKey)
+        return;
+      lastWatchPathKey = nextKey;
+      console.log("[agendex] watch paths changed, refreshing file watchers...");
+      startWatching(onPlansFileChange);
+    }, WATCHER_REFRESH_INTERVAL_MS);
+  }
   if (shouldEnablePlannotatorSync(config)) {
     setInterval(() => void pollPlannotatorWritebacks(), PLANNOTATOR_WRITEBACK_POLL_INTERVAL_MS);
     pollPlannotatorWritebacks();
     setInterval(() => {
       (async () => {
         await scan();
+        await enqueueChangedPlans(getAll());
         await reconcileLivePlannotatorSessions(getAll());
       })().catch((err) => {
         console.error("[agendex] Plannotator liveness sweep failed:", err);
       });
     }, PLANNOTATOR_LIVENESS_SWEEP_INTERVAL_MS);
+    if (LIVE_SESSION_POLL_MS > 0) {
+      setInterval(() => {
+        (async () => {
+          const ipAddress = await getSyncIpAddress();
+          const livePlans = getAll().filter((plan) => {
+            const payload = planToSyncPayload(plan, config.deviceId, hostname2, ipAddress);
+            return isLivePlannotatorPayload(payload);
+          });
+          if (livePlans.length === 0)
+            return;
+          await scan();
+          const refreshedLive = getAll().filter((plan) => {
+            const payload = planToSyncPayload(plan, config.deviceId, hostname2, ipAddress);
+            return isLivePlannotatorPayload(payload);
+          });
+          await enqueueChangedPlans(refreshedLive);
+        })().catch((err) => {
+          console.error("[agendex] live session poll failed:", err);
+        });
+      }, LIVE_SESSION_POLL_MS);
+    }
   }
-  startWatching((changedPlans) => {
-    (async () => {
-      const ipAddress = await getSyncIpAddress();
-      for (const plan of changedPlans) {
-        syncQueue.push(planToSyncPayload(plan, config.deviceId, hostname2, ipAddress));
-      }
-      processSyncQueue();
-      await reconcileLivePlannotatorSessions(getAll());
-    })().catch((err) => {
-      console.error("[agendex] failed to queue changed plans:", err);
-    });
-  });
+  startWatching(onPlansFileChange);
   console.log(`[agendex] daemon running. Watching for file changes...`);
   async function gracefulShutdown() {
     stopWatching();
@@ -4981,7 +5267,7 @@ async function startSupervisor() {
   };
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
-  const scriptPath = resolve6(process.argv[1] ?? fileURLToPath(new URL("./cli.ts", import.meta.url)));
+  const scriptPath = resolve7(process.argv[1] ?? fileURLToPath(new URL("./cli.ts", import.meta.url)));
   const restartTimes = [];
   while (!stopping) {
     const workerArgs = [scriptPath, "start", "--worker"];
@@ -4991,11 +5277,11 @@ async function startSupervisor() {
       stdio: ["ignore", "inherit", "inherit"],
       env: { ...process.env, ...isDevMode() ? { AGENDEX_DEV: "1" } : {} }
     });
-    const exitCode = await new Promise((resolve7) => {
-      workerProc?.once("exit", (code) => resolve7(code));
+    const exitCode = await new Promise((resolve8) => {
+      workerProc?.once("exit", (code) => resolve8(code));
       workerProc?.once("error", (error) => {
         console.error("[agendex] failed to spawn worker:", error);
-        resolve7(1);
+        resolve8(1);
       });
     });
     workerProc = null;
@@ -5021,7 +5307,7 @@ async function startSupervisor() {
 import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
 import { mkdir as mkdir2, rm, writeFile as writeFile4 } from "node:fs/promises";
 import { homedir as homedir10 } from "node:os";
-import { dirname as dirname4, join as join14, resolve as resolve7 } from "node:path";
+import { dirname as dirname4, join as join14, resolve as resolve8 } from "node:path";
 var SUPPORTED_AGENTS = ["claude-code", "codex", "pi"];
 var MANAGED_MARKER = "agendex-plan-review";
 var HOOK_TIMEOUT_SECONDS = 345600;
@@ -5033,7 +5319,7 @@ function commandFor(cliEntry, agent) {
   return `${shellQuote(process.execPath)} ${shellQuote(cliEntry)} review-plan --hook --agent ${agent}`;
 }
 function scopeRoot(scope) {
-  return scope === "repo" ? resolve7(process.env.PWD || process.cwd()) : homedir10();
+  return scope === "repo" ? resolve8(process.env.PWD || process.cwd()) : homedir10();
 }
 function hooksJsonPath(agent, scope) {
   const root = scopeRoot(scope);
@@ -5358,7 +5644,7 @@ async function runHooksCommand(args, cliEntry) {
     for (const agent of agents) {
       if (agent === "claude-code")
         printClaudePreviewWarning(dryRun);
-      const path = await installAgent(agent, scope, resolve7(cliEntry), dryRun);
+      const path = await installAgent(agent, scope, resolve8(cliEntry), dryRun);
       console.log(`[agendex] ${dryRun ? "would install" : "installed"} ${agent} hook: ${path}`);
     }
     return 0;
@@ -5448,7 +5734,7 @@ async function syncAll(force = false) {
 // src/upgrade.ts
 import { spawn as spawn3, spawnSync } from "node:child_process";
 import { realpathSync as realpathSync2 } from "node:fs";
-import { dirname as dirname5, resolve as resolve8, sep as sep4 } from "node:path";
+import { dirname as dirname5, resolve as resolve9, sep as sep4 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/version.ts
@@ -5458,7 +5744,7 @@ import { join as join15 } from "node:path";
 // package.json
 var package_default = {
   name: "agendex-cli",
-  version: "1.1.0",
+  version: "1.3.0",
   description: "Agendex CLI for login, sync, and daemon workflows",
   homepage: "https://github.com/Tyru5/Agendex#readme",
   bugs: {
@@ -5581,9 +5867,9 @@ var PACKAGE_NAME = "agendex-cli";
 var moduleDir = dirname5(fileURLToPath2(import.meta.url));
 function getPackageRoot() {
   try {
-    return realpathSync2(resolve8(moduleDir, ".."));
+    return realpathSync2(resolve9(moduleDir, ".."));
   } catch {
-    return resolve8(moduleDir, "..");
+    return resolve9(moduleDir, "..");
   }
 }
 function detectPackageManager(packageRoot) {
@@ -5765,9 +6051,120 @@ async function runUpgrade(opts) {
   });
 }
 
+// src/upload.ts
+import { readFile as readFile8, stat as stat8 } from "node:fs/promises";
+import { existsSync as existsSync12 } from "node:fs";
+import { hostname as osHostname4 } from "node:os";
+function resolveAgentOverride(args) {
+  const idx = args.indexOf("--agent");
+  if (idx === -1)
+    return;
+  const value = args[idx + 1];
+  if (value === undefined || value.startsWith("--"))
+    return "missing";
+  return value;
+}
+function resolvePathArg(args) {
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a === undefined)
+      continue;
+    if (a === "upload" || a === "--dev" || a === "--open")
+      continue;
+    if (a === "--agent") {
+      i++;
+      continue;
+    }
+    if (a.startsWith("--"))
+      continue;
+    return a;
+  }
+  return;
+}
+async function runUpload(args, deps) {
+  const syncPlanFn = deps?.syncPlan ?? syncPlan;
+  const log = deps?.log ?? ((m) => console.log(m));
+  const error = deps?.error ?? ((m) => console.error(m));
+  const openBrowser2 = deps?.openBrowser ?? launchBrowser;
+  const pathArg = resolvePathArg(args);
+  if (!pathArg || !pathArg.trim()) {
+    error("[agendex] usage: agendex upload <path> [--agent <name>] [--open]");
+    return 1;
+  }
+  const absolutePath = resolveCustomPlanDirPath(pathArg);
+  if (!existsSync12(absolutePath)) {
+    error(`[agendex] path does not exist: ${absolutePath}`);
+    return 1;
+  }
+  let stats;
+  try {
+    stats = await stat8(absolutePath);
+  } catch (err) {
+    error(`[agendex] could not read path: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  if (stats.isDirectory()) {
+    error(`[agendex] path is a directory, expected a single file: ${absolutePath}`);
+    return 1;
+  }
+  if (!/\.md$/i.test(absolutePath)) {
+    error(`[agendex] only Markdown (.md) files are supported: ${absolutePath}`);
+    return 1;
+  }
+  const config = loadConfig();
+  if (!config?.cloudToken || !config?.convexUrl) {
+    error("[agendex] not logged in. Run `agendex login` first.");
+    return 1;
+  }
+  let content;
+  try {
+    content = await readFile8(absolutePath, "utf-8");
+  } catch (err) {
+    error(`[agendex] could not read file: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  const agentOverride = resolveAgentOverride(args);
+  if (agentOverride === "missing") {
+    error("[agendex] usage: agendex upload <path> [--agent <name>] [--open]");
+    error("[agendex] --agent requires a name");
+    return 1;
+  }
+  const ipAddress = await shouldIncludeLocalIpAddressInSync() ? getLocalIpAddress() : undefined;
+  const payload = fileToSyncPayload(absolutePath, content, {
+    agentOverride,
+    deviceId: config.deviceId ?? loadOrCreateDeviceId(),
+    hostname: osHostname4(),
+    ipAddress,
+    createdAt: stats.birthtime.getTime(),
+    updatedAt: stats.mtime.getTime()
+  });
+  const result = await syncPlanFn(payload);
+  if (!result.ok) {
+    if (result.status === 403) {
+      error(`[agendex] ${result.error ?? "Cloud Pro subscription required"}`);
+      error(`[agendex] View plans and pricing: ${getSiteUrl().replace(/\/$/, "")}/#pricing`);
+      return 1;
+    }
+    error(`[agendex] upload failed: ${result.error ?? "unknown error"}`);
+    return 1;
+  }
+  if (result.skippedLowValue) {
+    log(`[agendex] "${payload.title}" was skipped as a low-value plan and was not stored in the cloud.`);
+    return 0;
+  }
+  const site = getSiteUrl().replace(/\/$/, "");
+  const planUrl = result.planId ? `${site}/dashboard?plan=${encodeURIComponent(result.planId)}` : `${site}/dashboard`;
+  log(`[agendex] uploaded "${payload.title}"`);
+  log(`[agendex] ${planUrl}`);
+  if (args.includes("--open")) {
+    openBrowser2(planUrl, "uploaded plan in your browser");
+  }
+  return 0;
+}
+
 // src/web.ts
 async function openAgendexWeb(siteUrlOverride) {
-  const base = siteUrlOverride ?? getDefaultSiteUrl();
+  const base = siteUrlOverride ?? getSiteUrl();
   const url = base.replace(/\/$/, "");
   launchBrowser(url, "Agendex in your browser");
 }
@@ -5802,7 +6199,7 @@ function firstCommandToken(argv) {
   return;
 }
 var command = firstCommandToken(args) ?? "start";
-var cliEntry = resolve9(process.argv[1] ?? fileURLToPath3(import.meta.url));
+var cliEntry = resolve10(process.argv[1] ?? fileURLToPath3(import.meta.url));
 async function main() {
   const isInternal = args.includes("--daemon") || args.includes("--worker");
   if (command === "--version" || command === "-v") {
@@ -5822,6 +6219,7 @@ async function main() {
     "add-dir",
     "remove-dir",
     "list-dirs",
+    "upload",
     "upgrade",
     "help",
     "--help",
@@ -5922,6 +6320,9 @@ async function main() {
       await syncAll(force);
       return 0;
     }
+    case "upload": {
+      return await runUpload(args);
+    }
     case "hooks": {
       return await runHooksCommand(args, cliEntry);
     }
@@ -6010,7 +6411,7 @@ async function main() {
         return 1;
       }
       const resolved = resolveCustomPlanDirPath(dirPath);
-      if (!existsSync12(resolved)) {
+      if (!existsSync13(resolved)) {
         writeStderr(`[agendex] path does not exist: ${resolved}`);
         return 1;
       }
@@ -6029,7 +6430,7 @@ async function main() {
         const { request } = await import("node:http");
         const body = JSON.stringify({ path: resolved });
         try {
-          const res = await new Promise((resolve10, reject) => {
+          const res = await new Promise((resolve11, reject) => {
             const req = request(`http://localhost:${port}/api/v1/plan-sources`, {
               method: "POST",
               headers: {
@@ -6043,7 +6444,7 @@ async function main() {
               res2.on("data", (chunk) => {
                 data += chunk;
               });
-              res2.on("end", () => resolve10({ status: res2.statusCode ?? 0, body: data }));
+              res2.on("end", () => resolve11({ status: res2.statusCode ?? 0, body: data }));
               res2.on("error", reject);
             });
             req.on("error", reject);
@@ -6203,6 +6604,9 @@ Usage:
   agendex list-dirs    List custom plan directories
   agendex sync         One-shot scan + sync to cloud (skips unchanged plans)
   agendex sync --force Re-sync all plans, ignoring cache
+  agendex upload <path>  Upload a single Markdown plan file to the cloud
+  agendex upload <path> --agent <name>  Override the uploaded plan's agent label
+  agendex upload <path> --open  Open the uploaded plan in the browser after upload
   agendex cleanup      Interactively remove cloud daemons
   agendex cleanup --stale  Auto-remove all stale daemons
   agendex status       Show current config state + daemon status
@@ -6236,13 +6640,13 @@ function flushStream(stream) {
   if (stream.destroyed || !stream.writable) {
     return Promise.resolve();
   }
-  return new Promise((resolve10, reject) => {
+  return new Promise((resolve11, reject) => {
     stream.write("", (error) => {
       if (error) {
         reject(error);
         return;
       }
-      resolve10();
+      resolve11();
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agendex-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Agendex CLI for login, sync, and daemon workflows",
   "homepage": "https://github.com/Tyru5/Agendex#readme",
   "repository": {