sdocs-dev 1.18.0 → 1.19.2

package/bin/sdocs-dev.js

@@ -64,7 +64,10 @@ function buildRouter() {
   r.register('comments', { handler: () => { console.log(helpText.COMMENTS_HELP); process.exit(0); } });
 
   // Setup / refresh / auto-update.
-  r.register('setup',       { handler: async (opts) => { await setup.runSetup({ force: true, yes: !!opts.yesFlag, dryRun: !!opts.dryRunFlag }); process.exit(0); } });
+  r.register('setup',       { handler: async (opts) => { await setup.runSetup({
+    force: true, yes: !!opts.yesFlag, dryRun: !!opts.dryRunFlag,
+    edition: opts.skillEdition, accountId: opts.accountFlag,
+  }); process.exit(0); } });
   r.register('refresh',     { handler: async () => { await setup.runRefresh(); process.exit(0); } });
   r.register('auto-update', { handler: (opts) => {
     // Sub-arg lives in opts.file (positional). Accept on/off/empty.
@@ -116,10 +119,15 @@ function buildRouter() {
   r.register('library',  { handler: async (opts) => { await libraryCommands.libraryCommand(opts); /* libraryOpen blocks */ } });
   r.register('cloud',    { handler: async (opts) => { await cloudCommands.runCloudCommand(opts); } });
 
-  r.register(null,       { handler: (opts) => {
-    // Index-on-open tap: fires before the open so any +tag CLI args land
-    // in the file's front matter before the browser receives the content.
-    libraryCommands.tapOpen(opts);
+  r.register(null,       { handler: async (opts) => {
+    const cloudFirst = setup.cloudFirstSettings();
+    if (cloudFirst) {
+      await cloudCommands.autoSyncOpen(opts, { accountId: cloudFirst.accountId });
+    } else {
+      // Index-on-open tap: fires before the open so any +tag CLI args land
+      // in the file's front matter before the browser receives the content.
+      libraryCommands.tapOpen(opts);
+    }
     return commands.openCommand(opts);
   } });
 
@@ -163,6 +171,9 @@ module.exports = {
   compressAndEncrypt: shortLink.compressAndEncrypt,
   uploadShortLink:    shortLink.uploadShortLink,
   buildShortUrl:      shortLink.buildShortUrl,
+  normalizePlacementId: shortLink.normalizePlacementId,
+  buildAttributionQuery: shortLink.buildAttributionQuery,
+  assembleShortUrl: shortLink.assembleShortUrl,
 
   // Default styles
   mergeStyles:        styles.mergeStyles,

package/lib/agent-block.js

@@ -28,16 +28,16 @@ const path = require('path');
 const { SETUP_CACHE } = require('./constants');
 
 // ── Skill model ────────────────────────────────────────────
-const SKILL_VERSION = 27;
-const SKILL_REASON  = 'Agents can now guide readers through rendered prose, rich blocks, and inline code lines.';
+const SKILL_VERSION = 29;
+const SKILL_REASON  = 'The Cloud edition now treats ordinary sdoc opens as automatic Cloud creates or updates and keeps tags in Cloud.';
 const SKILL_NAME    = 'smalldocs';
 
 // Always-in-context preamble. Concise trigger text; the full reference lives
 // in SKILL_BODY and loads on demand. Plain text: no backticks, no em/en dashes,
 // no double quotes (it is emitted as a double-quoted YAML scalar).
-const SKILL_DESCRIPTION = "Use SmallDocs when the user says sdoc, S-doc, smalldoc, sdoc this, or asks to open, present, share, style, save, or walk through a Markdown document with SmallDocs. Create or locate the Markdown file and use sdoc FILE.md for normal viewing. For a document walkthrough add source-line annotations to the sdoc command; the source file stays unchanged. For a presentation run sdoc slides, create a Markdown deck from the source material, run sdoc slides verify FILE.md --json and fix every error, then run sdoc present FILE.md. For a runnable browser component run sdoc apps, use a sdoc-app block, and check inline, fullscreen, narrow, and wide layouts. Run the matching bare reference command before other specialised syntax. Local files stay local unless the user explicitly requests sharing or Cloud storage.";
+const SKILL_DESCRIPTION = "Use SmallDocs when the user says sdoc, S-doc, smalldoc, sdoc this, or asks to open, present, share, style, save, or walk through a Markdown document with SmallDocs. Create or locate the Markdown file and use sdoc FILE.md for normal viewing. For a document walkthrough add source-line annotations to the sdoc command; the source file stays unchanged. For a presentation run sdoc slides, create a Markdown deck from the source material, run sdoc slides verify FILE.md --json and fix every error, then run sdoc present FILE.md. Use a runnable browser component only when the reader must interact with the result to understand something static document forms cannot express as clearly. When that criterion is met, run sdoc apps, use an sdoc-app block, and check inline, fullscreen, narrow, and wide layouts. Run the matching bare reference command before other specialised syntax. Local files stay local unless the user explicitly requests sharing or Cloud storage.";
 
-const CLOUD_SKILL_DESCRIPTION = "Use SmallDocs when the user says sdoc, S-doc, smalldoc, sdoc this, or asks to open, present, share, style, search, save, or walk through a Markdown document with SmallDocs. For a document walkthrough add source-line annotations to the sdoc command; the source file stays unchanged. For a presentation run sdoc slides, create a Markdown deck, run sdoc slides verify FILE.md --json and fix every error, then run sdoc present FILE.md. For a runnable browser component run sdoc apps, use a sdoc-app block, and check inline, fullscreen, narrow, and wide layouts. This user has enabled SmallDocs Cloud. Use sdoc FILE.md for ordinary local viewing and do not search Cloud when a named local source is sufficient. For relevant prior Cloud material run sdoc cloud status --json, search, then sdoc cloud pull DOCUMENT_UUID --output PATH --no-bind --json.";
+const CLOUD_SKILL_DESCRIPTION = "Use SmallDocs when the user says sdoc, S-doc, smalldoc, sdoc this, or asks to open, present, share, style, search, save, or walk through a Markdown document with SmallDocs. This user has enabled Cloud-first mode: use sdoc FILE.md for new and updated Markdown so the CLI automatically creates or updates the Cloud copy before opening it. Use +tag arguments for Cloud tags. For relevant prior Cloud material run sdoc cloud status --json, search, then pull. For a presentation run sdoc slides, create a Markdown deck, run sdoc slides verify FILE.md --json and fix every error, run sdoc FILE.md to store it, then run sdoc present FILE.md. Use a runnable browser component only when the reader must interact with the result to understand something static document forms cannot express as clearly. When that criterion is met, run sdoc apps and check inline, fullscreen, narrow, and wide layouts.";
 
 const STANDARD_CLOUD_SKILL_SECTION = `### SmallDocs Cloud is available
 
@@ -72,6 +72,8 @@ ${STANDARD_CLOUD_SKILL_SECTION}
 
 SmallDocs uses the browser to extend what Markdown can be: a styled doc, a chart, a diagram, a slide deck, or an interactive form whose answers come back to you. Reach for one of these when a visual or interactive artifact will land harder than prose - not as a default for every reply. To create something new, write the \`.md\` file first, then \`sdoc path/to/file.md\`.
 
+Use runnable HTML only when the interaction carries meaning that prose, a Mermaid diagram, a chart, or computed cells cannot express as clearly. Choose it when the reader must manipulate inputs, simulate behavior, rotate or zoom a spatial model, or explore linked states to understand the result. A three-input financial model may warrant an interactive surface when the relationship between assumptions matters; exact values alone normally belong in cells or a table. Before authoring, state what the interaction helps the reader understand. If the reason describes only appearance or layout, use a static document form.
+
 Each command below prints its reference when run with no arguments - run it before writing the matching fenced block. The JSON / DSL shapes are specific and easy to get wrong from memory.
 
 For a presentation request, follow this sequence rather than treating it as an ordinary document:
@@ -83,7 +85,7 @@ For a presentation request, follow this sequence rather than treating it as an o
 
 - \`sdoc charts\` - rendering inline charts (\`\`\`chart blocks)
 - \`sdoc diagrams\` - rendering inline Mermaid diagrams (\`\`\`mermaid blocks; has full-screen mode for zoom). Reach for this when drawing system or architectural diagrams (sequence, flow, component layout) - a diagram often communicates the shape of something faster than the equivalent prose.
-- \`sdoc apps\` - runnable HTML components (\`\`\`sdoc-app blocks): one complete HTML document with its own CSS, JavaScript, and data. Start with semantic HTML: SmallDocs supplies the document's current typography, colours, spacing, background, and control treatment in a low-priority CSS layer. Ordinary component CSS wins, and the \`--sdoc-app-*\` custom properties support targeted overrides. Let the tool's purpose determine its layout: prefer a clear page, list, table, or form before a dashboard of cards, use a canvas or stage for spatial interaction, and add surfaces, colour, and distinctive shapes when they encode structure or state. The component's document layout owns its inline height, while its width follows the reading column. Write responsive CSS for both the column and fullscreen viewport. It expands without losing state and joins Previous / Next navigation when the document contains several components. Use \`<title>\` to name it. Ordinary \`\`\`html remains source. Run \`sdoc apps\` before authoring and test every control inline, fullscreen, narrow, and wide.
+- \`sdoc apps\` - runnable HTML components (\`\`\`sdoc-app blocks): one complete HTML document with its own CSS, JavaScript, and data. Use it when manipulation, simulation, spatial navigation, or linked states communicate something prose, diagrams, charts, or cells cannot express as clearly. If a static form communicates the result equally well, use it. Start with semantic HTML: SmallDocs supplies the document's current typography, colours, spacing, background, and control treatment in a low-priority CSS layer. Ordinary component CSS wins, and the \`--sdoc-app-*\` custom properties support targeted overrides. Let the tool's purpose determine its layout: prefer a clear page, list, table, or form before a dashboard of cards, use a canvas or stage for spatial interaction, and add surfaces, colour, and distinctive shapes when they encode structure or state. The component's document layout owns its inline height, while its width follows the reading column. Write responsive CSS for both the column and fullscreen viewport. It expands without losing state and joins Previous / Next navigation when the document contains several components. Use \`<title>\` to name it. Ordinary \`\`\`html remains source. Run \`sdoc apps\` before authoring and test every control inline, fullscreen, narrow, and wide.
 - \`sdoc slides\` - inline slide decks (\`\`\`slide / ~~~slide blocks; has full-screen presentation mode). Slides can be standalone exported as \`.pdf\` or \`.pptx\`. Run \`sdoc slides verify file.md --json\` after authoring; fix every diagnostic, or add \`bleed=allow\` only to an individual shape whose off-canvas placement is intentional, then rerun until it exits 0. Use \`sdoc present file.md\` for the visual check that headless validation cannot perform.
 - \`sdoc cells\` - rendering spreadsheets (\`\`\`cells blocks): CSV rows where plain values and =formulas (SUM, AVERAGE, IF, ROUND...) sit in the same grid and compute live. The reader can sort, select ranges for quick stats, edit a scratch copy fullscreen, and download the sheet as Excel (.xlsx) with the formulas still working. Name a block (\`\`\`cells Expenses) to build a workbook of several tabs whose formulas reference each other across sheets (\`=Expenses!B4\`); run \`sdoc cells verify file.md\` to compute the whole workbook headlessly and read the values back. Reach for this when handing the user numbers they will want to check or play with - totals, budgets, projections. \`sdoc report.csv\` opens a CSV file directly as a sheet.
 - \`sdoc code\` - opening a source file or a fenced code block as a syntax-highlighted listing: a light code viewer for reading code with the user away from the IDE. \`sdoc app.rb\` (or \`.js\`, \`.py\`, \`.go\`, \`.rs\`, \`.ts\`...) opens a file as a highlighted listing; a \`\`\`lang fenced block is highlighted inline. Comments in the source get a prominent lane so the code reads clearly top to bottom. The fullscreen view adds a line-number gutter and language-aware folding (collapse a whole method or class); a comment mode lets the user annotate a line or method with review notes, kept in the browser rather than the file. You can also pin your own explanations to lines as you open a file - \`sdoc app.py 22:"the bug is here" 25-28:"wrong comparison"\` - and the file opens as a guided walkthrough: each note is a markdown callout below its line with a Prev / Next stepper, walked in the order you pass the notes (not line order). Name several files to narrate across them - \`sdoc app.py 5:"entry point" util.py 12:"it calls into here" app.py 9:"back here"\` - and each becomes a tab the walkthrough hops between. When the user asks you to walk them through code, an MR, a diff, or the current changes, build one of these. The file rides in the URL like any document; nothing is uploaded. Reach for it when reading or reviewing code with the user, not for prose.
@@ -93,7 +95,9 @@ For a presentation request, follow this sequence rather than treating it as an o
 
 const CLOUD_SKILL_SECTION = `### SmallDocs Cloud for agents
 
-This user has enabled SmallDocs Cloud. Local viewing remains the default when the request only asks to create or open a document. Consider Cloud without waiting for the user to say the word "Cloud" when the existing conversation or task calls for persistent storage, cross-device access, search, revisions, permissions, or notifications. If the intended destination is unclear and it changes who can access the document, discuss it with the user.
+This user has enabled Cloud-first mode. Treat Cloud as the normal destination for SmallDocs Markdown. Write or update the local Markdown working copy, then run \`sdoc FILE.md\`. The CLI creates a Cloud document for an unbound file or pushes a revision for a bound file before it opens the browser. If the Cloud write fails, stop and report the error instead of presenting the local copy as saved.
+
+Use \`sdoc FILE.md +tag1 +tag2\` to add Cloud tags. Do not add SmallDocs tags to local front matter and do not use the local library. Use \`sdoc cloud ls\`, \`sdoc cloud search\`, and \`sdoc cloud tags\` for discovery. Use \`sdoc share\` only when the user explicitly asks for an encrypted snapshot link rather than the managed Cloud document.
 
 Treat Cloud as a source of context, not only a place to save new work. When earlier decisions, research, plans, or documentation could materially inform the task, search Cloud before recreating that context. Use specific project terms first and try shorter terms or existing tags when a search returns nothing. Do not search unrelated Cloud documents merely because Cloud is enabled.
 
@@ -114,11 +118,24 @@ When earlier Cloud material should inform new work, use this sequence:
 - When updating a bound document, the local binding supplies the revision the agent edited. Cloud keeps separate changes from other writers; overlapping replacements may both remain. If the server combines content and the file did not change during upload, push writes the combined Markdown back to the local file. Inspect \`merge_classification\`, \`combined\`, and \`local_updated_from_cloud\` in the JSON result.
 - Inspect or recover history with \`sdoc cloud history DOCUMENT_UUID\` and \`sdoc cloud restore DOCUMENT_UUID --revision REVISION_UUID\`.
 
-Cloud documents are identified by UUID, not filename. An account is the billing and access boundary; tags organize documents inside it. Do not use \`sdoc share\` as a substitute for Cloud: share creates an encrypted snapshot link, while Cloud provides revisions, search, membership, and persistent agent access.
+Cloud documents are identified by UUID, not filename. An account is the access boundary; tags organize documents inside it. The local file remains the editable working copy and its binding records the Cloud document and base revision.
 
 `;
 
-const CLOUD_SKILL_BODY = SKILL_BODY.replace(STANDARD_CLOUD_SKILL_SECTION, CLOUD_SKILL_SECTION);
+const CLOUD_SKILL_BODY = SKILL_BODY
+  .replace(
+    'The `sdoc` CLI (`sdoc path/to/file.md`) is installed globally and renders local Markdown files securely in the browser (at https://smalldocs.org) in a way that\'s comfortable for your user to read and share. Nothing hits a server unless the user explicitly saves the file to the SmallDocs cloud or runs `sdoc share`.',
+    'The `sdoc` CLI (`sdoc path/to/file.md`) is installed globally and renders Markdown in the browser at https://smalldocs.org. Cloud-first mode uploads a new Markdown file or pushes a bound file before opening it, so the Cloud copy stays current while the local file remains the editable working copy.',
+  )
+  .replace(
+    '- `sdoc file.md` - the default way to open a file, for comfortable reading or quick sharing.',
+    '- `sdoc file.md` - create or update the Cloud document, then open it for reading.',
+  )
+  .replace(
+    '- `sdoc library` - opens a library view containing files previously opened with `sdoc path/to/file.md`; filter by directory, date, or tags (the index doesn\'t search file content - fall back to `grep` for that). Opt out per-file with `sdocs-library: false` in front matter. (`sdoc library --help` for the full reference.)\n- `sdoc library ls --tags` - list the current project\'s tags by frequency. When tags would make a document worth rediscovering, run this before choosing them. Prefer an existing tag that fits; introduce a new one when none does.\n- `sdoc file.md +tag1 +tag2` - open the file and add the selected tags to its YAML front matter. The `+` prefix is shell-safe and the tags persist.',
+    '- `sdoc cloud ls` - list documents in Cloud.\n- `sdoc cloud tags` - list Cloud tags by frequency. Prefer an existing tag that fits when the document should be easy to find again.\n- `sdoc file.md +tag1 +tag2` - create or update the Cloud document and add the selected Cloud tags. The local Markdown is not changed.',
+  )
+  .replace(STANDARD_CLOUD_SKILL_SECTION, CLOUD_SKILL_SECTION);
 
 function formatSkill(version, options) {
   const cloud = Boolean(options && options.cloud);

package/lib/agent-files.js

@@ -110,7 +110,7 @@ function pathsResolveSame(a, b) {
 
 // ── canonical skill ────────────────────────────────────────
 
-function refreshCanonicalSkill(home) {
+function refreshCanonicalSkill(home, opts = {}) {
   home = home || os.homedir();
   const file = canonicalSkillFile(home);
   let existing = null;
@@ -130,23 +130,27 @@ function refreshCanonicalSkill(home) {
   }
   const currentVersion = existing ? readSkillVersion(existing) : null;
   const currentEdition = existing ? readSkillEdition(existing) : 'standard';
+  const requestedEdition = opts.edition === 'cloud' || opts.edition === 'standard'
+    ? opts.edition : null;
+  const desiredEdition = requestedEdition || currentEdition;
   if (existing !== null && currentVersion === null) {
     return {
       changed: false, reason: 'conflict', path: file,
       error: 'existing canonical SKILL.md is not managed by SmallDocs; left untouched',
     };
   }
-  if (currentVersion === SKILL_VERSION) {
+  if (currentVersion === SKILL_VERSION && currentEdition === desiredEdition) {
     return { changed: false, reason: 'current', path: file };
   }
   if (currentVersion !== null && currentVersion > SKILL_VERSION) {
     return { changed: false, reason: 'newer', path: file };
   }
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  atomicWrite(file, formatSkill(SKILL_VERSION, { cloud: currentEdition === 'cloud' }));
+  atomicWrite(file, formatSkill(SKILL_VERSION, { cloud: desiredEdition === 'cloud' }));
   return {
     changed: true, path: file,
     fromVersion: currentVersion || 0, toVersion: SKILL_VERSION,
+    fromEdition: currentEdition, toEdition: desiredEdition,
   };
 }
 
@@ -298,7 +302,7 @@ function syncAgentSkill(opts = {}) {
   const canonicalDir = canonicalSkillDir(home);
 
   const result = {
-    canonical: refreshCanonicalSkill(home),
+    canonical: refreshCanonicalSkill(home, { edition: opts.edition }),
     links: [],
     stripped: [],
     errors: [],

package/lib/cloud-commands.js

@@ -6,6 +6,7 @@ const constants = require('./constants');
 const io = require('./io');
 const credentialStore = require('./cloud-credentials');
 const bindings = require('./cloud-bindings');
+const SDocYaml = require('../shared/sdocs-yaml.js');
 
 const EXIT = { unexpected: 1, invalid_request: 2, login_required: 3,
   resource_unavailable: 4, account_required: 4, account_selection_required: 4,
@@ -21,8 +22,8 @@ const EXIT = { unexpected: 1, invalid_request: 2, login_required: 3,
 const CLOUD_HELP = `SmallDocs Cloud
 
 Cloud stores selected Markdown documents with search, revisions, member access,
-and cross-device CLI and browser access. Local files are not uploaded until a
-create or push command changes Cloud.
+and cross-device CLI and browser access. Run \`sdoc setup --cloud --yes\` to make
+ordinary \`sdoc FILE.md\` opens create or update the Cloud document first.
 
 DISCOVER AND READ
 
@@ -210,6 +211,7 @@ class CloudClient {
 function emit(opts, command, value, human) {
   if (opts.jsonFlag) process.stdout.write(JSON.stringify(Object.assign({ ok: true, command }, value)) + '\n');
   else process.stdout.write((human || JSON.stringify(value, null, 2)) + '\n');
+  return value;
 }
 
 function skillInstallCommand(originValue, cloud) {
@@ -234,13 +236,15 @@ function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
 
 async function login(opts, client) {
   const installCommand = skillInstallCommand(client.origin, true);
+  const setupCommand = 'sdoc setup --cloud --yes';
   if (client.loadCredential()) {
     try {
       const me = await client.authenticated('/api/cloud/v1/me');
       return emit(opts, 'cloud.login', { user: me.user, already_logged_in: true,
-        skill_mode: 'cloud', skill_install_command: installCommand },
+        skill_mode: 'cloud', skill_install_command: installCommand,
+        cloud_first_setup_command: setupCommand },
         'Already signed in as ' + (me.user.email || me.user.id) + '.\n' +
-        'Install or refresh the Cloud-aware SmallDocs skill:\n' + installCommand);
+        'Enable Cloud-first SmallDocs on this machine:\n' + setupCommand);
     } catch (_) {}
   }
   const issued = await client.raw('/api/cloud/v1/cli/device-authorizations', {
@@ -266,10 +270,10 @@ async function login(opts, client) {
     client.saveCredential(credential);
     return emit(opts, 'cloud.login', { user_id: credential.user_id,
       credential_id: credential.credential_id, skill_mode: 'cloud',
-      skill_install_command: installCommand },
+      skill_install_command: installCommand,
+      cloud_first_setup_command: setupCommand },
     'Cloud login saved for this machine.\n' +
-    'Install the Cloud-aware SmallDocs skill so agents can discover Cloud when relevant:\n' +
-    installCommand);
+    'Enable Cloud-first SmallDocs on this machine:\n' + setupCommand);
   }
   throw new CloudCommandError('login_required', 'Authorization expired before it was approved.');
 }
@@ -282,11 +286,13 @@ async function logout(opts, client) {
     client.credentials.remove(client.origin);
   }
   const restoreCommand = skillInstallCommand(client.origin, false);
+  const standardSetupCommand = 'sdoc setup --standard --yes';
   emit(opts, 'cloud.logout', { logged_out: true, skill_unchanged: true,
-    standard_skill_install_command: restoreCommand },
+    standard_skill_install_command: restoreCommand,
+    standard_setup_command: standardSetupCommand },
   'Signed out of SmallDocs Cloud. The installed skill was not changed.\n' +
-  'If you do not expect to use Cloud on this machine, restore the standard skill:\n' +
-  restoreCommand);
+  'If you do not expect to use Cloud on this machine, restore local-first behavior:\n' +
+  standardSetupCommand);
 }
 
 function filterTags(documents, tags) {
@@ -460,7 +466,7 @@ async function create(opts, client) {
   bindings.cacheBase(credential.user_id, document.id, document.current_revision_id, content);
   bindings.clearPending(credential.user_id, file);
   const localChanged = bindings.hash(fs.readFileSync(file)) !== digest;
-  emit(opts, 'cloud.create', { document_id: document.id, revision_id: document.current_revision_id,
+  return emit(opts, 'cloud.create', { document_id: document.id, revision_id: document.current_revision_id,
     revision_number: document.revision_number,
     account_id: response.account && response.account.id || opts.accountFlag || null, path: file,
     tags: document.tags, sha256: digest, binding_created: true,
@@ -533,21 +539,32 @@ async function push(opts, client) {
     throw new CloudCommandError('unsafe_local_state',
       'file is not bound; provide both --document and --base-revision');
   }
-  const content = fs.readFileSync(file, 'utf8');
-  const digest = bindings.hash(content);
+  const localContent = fs.readFileSync(file, 'utf8');
+  const digest = bindings.hash(localContent);
   if (binding.content_sha256 === digest) {
     return emit(opts, 'cloud.push', { document_id: binding.document_id,
       base_revision_id: binding.revision_id, revision_id: binding.revision_id,
       sha256: digest, no_change: true }, 'No changes to push.');
   }
+  const targetMarkdown = bindings.readBase(credential.user_id, binding.document_id,
+    binding.revision_id);
+  let content = localContent;
+  if (opts.cloudFirst && targetMarkdown != null) {
+    const cloudMeta = SDocYaml.parseFrontMatter(targetMarkdown).meta || {};
+    const cloudTags = Array.isArray(cloudMeta.tags) ? cloudMeta.tags : [];
+    if (cloudTags.length) {
+      const parsed = SDocYaml.parseFrontMatter(localContent);
+      const meta = Object.assign({}, parsed.meta, { tags: cloudTags });
+      content = SDocYaml.serializeFrontMatter(meta) + '\n' + parsed.body;
+    }
+  }
+  const uploadDigest = bindings.hash(content);
   let pending = bindings.getPending(credential.user_id, file);
-  if (!pending || pending.document_id !== binding.document_id || pending.base_revision_id !== binding.revision_id || pending.sha256 !== digest) {
+  if (!pending || pending.document_id !== binding.document_id || pending.base_revision_id !== binding.revision_id || pending.sha256 !== uploadDigest) {
     pending = { document_id: binding.document_id, base_revision_id: binding.revision_id,
-      sha256: digest, idempotency_key: crypto.randomUUID() };
+      sha256: uploadDigest, idempotency_key: crypto.randomUUID() };
     bindings.setPending(credential.user_id, file, pending);
   }
-  const targetMarkdown = bindings.readBase(credential.user_id, binding.document_id,
-    binding.revision_id);
   const response = await client.authenticated('/api/cloud/v1/documents/' + encodeURIComponent(binding.document_id) + '/revisions', {
     method: 'POST', headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ target_revision_id: binding.revision_id,
@@ -557,17 +574,27 @@ async function push(opts, client) {
   const document = response.document;
   const localChanged = bindings.hash(fs.readFileSync(file)) !== digest;
   const savedContent = typeof document.markdown === 'string' ? document.markdown : content;
-  const savedDigest = bindings.hash(savedContent);
-  const localUpdated = !localChanged && savedContent !== content;
+  let savedLocalContent = savedContent;
+  if (opts.cloudFirst) {
+    const saved = SDocYaml.parseFrontMatter(savedContent);
+    const local = SDocYaml.parseFrontMatter(localContent);
+    const meta = Object.assign({}, saved.meta);
+    if (Object.hasOwn(local.meta || {}, 'tags')) meta.tags = local.meta.tags;
+    else delete meta.tags;
+    savedLocalContent = Object.keys(meta).length
+      ? SDocYaml.serializeFrontMatter(meta) + '\n' + saved.body : saved.body;
+  }
+  const savedDigest = bindings.hash(savedLocalContent);
+  const localUpdated = !localChanged && savedLocalContent !== localContent;
   if (!localChanged) {
-    if (localUpdated) atomicFileWrite(file, savedContent);
+    if (localUpdated) atomicFileWrite(file, savedLocalContent);
     bindings.set(credential.user_id, file, { document_id: document.id,
       revision_id: document.current_revision_id, content_sha256: savedDigest,
       updated_at: document.updated_at });
   }
   bindings.cacheBase(credential.user_id, document.id, document.current_revision_id, savedContent);
   bindings.clearPending(credential.user_id, file);
-  emit(opts, 'cloud.push', { document_id: document.id, base_revision_id: binding.revision_id,
+  return emit(opts, 'cloud.push', { document_id: document.id, base_revision_id: binding.revision_id,
     revision_id: document.current_revision_id, revision_number: document.revision_number,
     tags: document.tags, sha256: savedDigest, no_change: false,
     merge_classification: document.merge_classification || 'clean',
@@ -579,6 +606,64 @@ async function push(opts, client) {
         : localUpdated ? ' and updated the local file with Cloud changes.' : '.'));
 }
 
+function isMarkdownFile(file) {
+  return /\.(?:md|markdown|mdown|mkd)$/i.test(String(file || ''));
+}
+
+async function addCloudTags(documentId, requestedTags, client, local) {
+  const additions = Array.from(new Set((requestedTags || [])
+    .map((tag) => String(tag).trim().toLowerCase()).filter(Boolean)));
+  if (!additions.length) return null;
+  const current = await client.authenticated('/api/cloud/v1/documents/'
+    + encodeURIComponent(documentId));
+  const existing = current.document && Array.isArray(current.document.tags)
+    ? current.document.tags : [];
+  const tags = Array.from(new Set(existing.concat(additions)));
+  if (tags.length === existing.length && tags.every((tag, index) => tag === existing[index])) {
+    return current.document;
+  }
+  const response = await client.authenticated('/api/cloud/v1/documents/'
+    + encodeURIComponent(documentId) + '/tags', {
+    method: 'PATCH', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ tags,
+      expected_head_revision_id: current.document.current_revision_id,
+      idempotency_key: crypto.randomUUID() }),
+  });
+  if (local && typeof response.document.markdown === 'string') {
+    const content = fs.readFileSync(local.file, 'utf8');
+    bindings.set(local.credential.user_id, local.file, {
+      document_id: documentId,
+      revision_id: response.document.current_revision_id,
+      content_sha256: bindings.hash(content),
+      updated_at: response.document.updated_at,
+    });
+    bindings.cacheBase(local.credential.user_id, documentId,
+      response.document.current_revision_id, response.document.markdown);
+  }
+  process.stdout.write('Updated Cloud tags for ' + documentId + '.\n');
+  return response.document;
+}
+
+async function autoSyncOpen(opts, dependencies) {
+  if (!opts.file || !isMarkdownFile(opts.file)) return { synced: false };
+  const client = dependencies && dependencies.client || new CloudClient();
+  const accountId = opts.accountFlag || dependencies && dependencies.accountId || null;
+  const file = requireFile(opts.file);
+  const credential = requireCredential(client);
+  const binding = bindings.get(credential.user_id, file);
+  const syncOpts = Object.assign({}, opts, {
+    extra: file,
+    accountFlag: accountId,
+    jsonFlag: false,
+    cloudFirst: true,
+  });
+  const result = binding ? await push(syncOpts, client) : await create(syncOpts, client);
+  const tagged = await addCloudTags(result.document_id, opts.addTags, client,
+    { credential, file });
+  return { synced: true, documentId: result.document_id,
+    revisionId: tagged && tagged.current_revision_id || result.revision_id, created: !binding };
+}
+
 async function history(opts, client) {
   const documentId = opts.extra;
   if (!documentId) throw new CloudCommandError('invalid_request',
@@ -737,5 +822,5 @@ async function runCloudCommand(opts, dependencies) {
   }
 }
 
-module.exports = { CloudClient, CloudCommandError, runCloudCommand, filterTags, origin, EXIT, CLOUD_HELP,
-  CLOUD_OVERVIEW, entitlementFailure, skillInstallCommand };
+module.exports = { CloudClient, CloudCommandError, runCloudCommand, autoSyncOpen, filterTags, origin,
+  EXIT, CLOUD_HELP, CLOUD_OVERVIEW, entitlementFailure, skillInstallCommand };

package/lib/cloud-credentials.js

@@ -115,7 +115,7 @@ function keychainOperations(operations) {
     return {
       read() { return null; },
       write(account, value) { keychainWriteAccount(account, value, operations); },
-      remove: keychainDeleteAccount,
+      remove() {},
     };
   }
   return {

package/lib/commands.js

@@ -44,6 +44,7 @@ async function finishUrl(opts, content, local, defaults) {
     try {
       const url = await buildShortUrl(content, {
         url: opts.url, mode: opts.mode, theme: opts.theme, section: opts.section,
+        source: opts.sourceFlag, placement: opts.placementFlag,
       });
       return { url, contentPresent: !!content };
     } catch (e) {
@@ -186,7 +187,7 @@ async function prepareUrl(opts) {
 // The non-blocking, share-by-URL case is `sdoc share <file>`.
 async function openCommand(opts) {
   const { url } = await prepareUrl(opts);
-  openBrowser(url);
+  if (!opts.noOpenFlag) openBrowser(url);
   console.log(`SDocs → ${url.length > 80 ? url.slice(0, 77) + '...' : url}`);
   await postCommandHooks();
 }

package/lib/help-text.js

@@ -20,6 +20,10 @@ USAGE
   sdoc share <file>                Copy shareable link to clipboard
   sdoc share <file> --section "X"  Link with section anchor
   sdoc share <file> --short        Encrypted /s/<id> short link (see SHORT LINKS)
+  sdoc share <file> --short --source email-launch
+                                   Short link attributed to a named source
+  sdoc share <file> --short --source x --placement launch-reply-01
+                                   Social link attributed to one placement
   sdoc schema                      Print the full styles schema
   sdoc charts                      Chart types, options, and styling guide
   sdoc diagrams                    Mermaid diagrams reference (\`\`\`mermaid blocks)
@@ -55,6 +59,9 @@ USAGE
   sdoc defaults                    Show ~/.sdocs/styles.yaml
   sdoc defaults --reset            Remove default styles
   sdoc setup                       Install the SmallDocs skill for your coding agents
+  sdoc setup --cloud --yes         Enable Cloud-first opens and install the Cloud skill
+  sdoc setup --cloud --account ID  Use one Cloud account for automatic creates
+  sdoc setup --standard --yes      Return to local-first behavior
   sdoc refresh                     Refresh the SmallDocs skill to the current version
   sdoc auto-update [on|off]        Toggle auto-install of sdoc updates
   sdoc upgrade                     Upgrade sdoc to the latest version now
@@ -83,7 +90,12 @@ OPTIONS
   --mode <m>            Alias for --read / --write / --style / --raw / --comment
   --short               Use the encrypted /s/<id> short-URL form (share
                         subcommand only). See SHORT LINKS below.
+  --source <name>       Attribute short-link visits to a source or campaign.
+  --placement <id>      Attribute a social short link to one publishing
+                        placement. Use 4-32 letters, numbers, underscores,
+                        or hyphens with --source x, yt, or youtube.
   --json                Machine-readable output for safe and Cloud commands.
+  --no-open             Do not launch the browser after a normal file open.
   --audit               Also print GitHub links to server-side source
                         files (safe subcommand only).
   --keep-open           feedback subcommand: keep the bridge alive across
@@ -202,6 +214,21 @@ SHORT LINKS (sdoc share --short)
 
   \`--short\` produces a shorter, encrypted form: \`https://smalldocs.org/s/<id>#k=<key>\`.
 
+  Add any source name when publishing a link, for example
+  \`--source email-launch\`, \`--source product-hunt\`, or \`--source x\`.
+  This produces a URL such as
+  \`https://smalldocs.org/s/<id>?src=email-launch#k=<key>\`. The source appears
+  automatically at \`/analytics/sources\`; the visit still counts in the
+  ordinary visit and short-link totals.
+
+  Add \`--placement launch-reply-01\` to an X or YouTube source link
+  when the same document is published in more than one place. This produces
+  \`https://smalldocs.org/s/<id>?src=x&pid=launch-reply-01#k=<key>\`.
+  The placement id is public and identifies the post, reply, or comment where
+  the link was used. It does not identify a visitor. Only links with a valid
+  placement id appear in the targeted-placement table at
+  \`/analytics/sources?type=short\`.
+
   How it works:
     1. The CLI brotli-compresses the content, generates a 256-bit AES-GCM
        key + 96-bit nonce locally, and encrypts the compressed bytes.
@@ -218,6 +245,8 @@ SHORT LINKS (sdoc share --short)
   What the server can see:
     - That a ciphertext blob was uploaded under id <id>.
     - When it was fetched and from which IP (standard server logs).
+    - For an opted-in placement link, its source, public placement id, and
+      short-link id when a visit is counted.
   What the server cannot see:
     - The plaintext document. It does not have the key.
     - The key. The key never leaves the URL fragment.

package/lib/io.js

@@ -39,6 +39,8 @@ function parseArgs(argv) {
   let url = null;
   let subcommand = null;
   let section = null;
+  let sourceFlag = null;
+  let placementFlag = null;
   let theme = null;
   let resetFlag = false;
   let shortFlag = false;
@@ -55,6 +57,7 @@ function parseArgs(argv) {
   let helpFlag = false;
   let yesFlag = false;
   let dryRunFlag = false;
+  let skillEdition = null;
   let sheetName = null;
   let projectFlag = null;
   let accountFlag = null;
@@ -115,6 +118,8 @@ function parseArgs(argv) {
 
     if (arg === '--url') { url = args[++i]; continue; }
     if (arg === '--section' || arg === '-s') { section = args[++i]; continue; }
+    if (arg === '--source') { sourceFlag = args[++i]; continue; }
+    if (arg === '--placement') { placementFlag = args[++i]; continue; }
     if (arg === '--reset') { resetFlag = true; continue; }
     if (arg === '--short') { shortFlag = true; continue; }
     if (arg === '--json')  { jsonFlag  = true; continue; }
@@ -132,6 +137,8 @@ function parseArgs(argv) {
     if (arg === '--tags')                            { tagsFlag         = true; continue; }
     if (arg === '--yes' || arg === '-y')             { yesFlag          = true; continue; }
     if (arg === '--dry-run')                         { dryRunFlag       = true; continue; }
+    if (arg === '--cloud')                           { skillEdition     = 'cloud'; continue; }
+    if (arg === '--standard')                        { skillEdition     = 'standard'; continue; }
     if (arg === '--sheet')                           { sheetName        = args[++i]; continue; }
     if (arg === '--project')                         { projectFlag      = args[++i]; continue; }
     if (arg === '--account')                         { accountFlag      = args[++i]; continue; }
@@ -198,11 +205,11 @@ function parseArgs(argv) {
   }
 
   return {
-    file, extra, mode, url, subcommand, section, theme,
+    file, extra, mode, url, subcommand, section, sourceFlag, placementFlag, theme,
     resetFlag, shortFlag, jsonFlag, auditFlag, waitFlag,
     messageText, connectTimeoutS, idleTimeoutS, reconnectGraceMs,
     keepOpenFlag, logFile,
-    tagsFlag, helpFlag, yesFlag, dryRunFlag, sheetName,
+    tagsFlag, helpFlag, yesFlag, dryRunFlag, skillEdition, sheetName,
     projectFlag, accountFlag, outputPath, revisionFlag, documentFlag, baseRevisionFlag,
     limitFlag, noOpenFlag, noBindFlag, forceFlag, tagFilters,
     everyoneFlag, onlyYouFlag, sharedWithMeFlag, noteText, memberFlags, documentFlags,

package/lib/setup.js

@@ -20,6 +20,7 @@ const {
   SKILL_BODY,
   SKILL_NAME,
   formatSkill,
+  readSkillEdition,
   canonicalSkillFile,
   canonicalSkillDir,
   legacyBlockTargets,
@@ -80,12 +81,13 @@ async function askAutoRefreshConsent() {
 // Preview what setup would do: print the skill, the symlinks it would create,
 // the agents covered by the canonical copy, and any legacy blocks it would
 // strip. Touches no file and writes no state.
-function dryRunPreview() {
+function dryRunPreview(edition) {
   const home = os.homedir();
   const env = process.env;
+  edition = edition || installedEdition(home);
   const skillPath = canonicalSkillFile(home);
   console.log(`--- ${skillPath} ---`);
-  console.log(formatSkill(SKILL_VERSION));
+  console.log(formatSkill(SKILL_VERSION, { cloud: edition === 'cloud' }));
 
   const detected = detectSkillAgents(home, env);
   const linked = detected.filter(a => !a.universal);
@@ -116,7 +118,31 @@ function dryRunPreview() {
   }
 }
 
-async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
+function installedEdition(home) {
+  try { return readSkillEdition(fs.readFileSync(canonicalSkillFile(home), 'utf8')); }
+  catch (_) { return 'standard'; }
+}
+
+function setupStateFields(edition, accountId, existing) {
+  const activeEdition = edition || installedEdition(os.homedir());
+  return {
+    skillEdition: activeEdition,
+    cloudAccountId: activeEdition === 'cloud'
+      ? (accountId || existing && existing.cloudAccountId || null) : null,
+  };
+}
+
+function cloudFirstSettings() {
+  const state = readSetupState();
+  if (state) {
+    if (state.declined || state.skillEdition !== 'cloud') return null;
+    return { accountId: state.cloudAccountId || null };
+  }
+  return installedEdition(os.homedir()) === 'cloud' ? { accountId: null } : null;
+}
+
+async function runSetup({ force = false, yes = false, dryRun = false,
+  edition = null, accountId = null } = {}) {
   if (!force) {
     if (!process.stdout.isTTY || !process.stdin.isTTY) return;
     if (process.env.CI || process.env.SDOCS_NO_SETUP) return;
@@ -125,9 +151,10 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
 
   // ── --yes (non-interactive) path ───────────────────────────
   if (yes) {
-    if (dryRun) { dryRunPreview(); return; }
+    if (dryRun) { dryRunPreview(edition); return; }
 
-    const result = syncAgentSkill({});
+    const existing = readSetupState();
+    const result = syncAgentSkill({ edition });
     const changed = syncChanged(result);
     const detected = detectSkillAgents(os.homedir(), process.env);
 
@@ -153,6 +180,7 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
       autoRefreshAgentFiles: true,
       autoInstallUpdates: false,
       lastRunVersion: VERSION,
+      ...setupStateFields(edition, accountId, existing),
     });
     return;
   }
@@ -181,7 +209,9 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
 
   const RULE = '\u2550'.repeat(36);
   console.log(`\n${RULE} Skill body ${RULE}`);
-  console.log(SKILL_BODY.trim());
+  const displayEdition = edition || installedEdition(home);
+  console.log(formatSkill(SKILL_VERSION, { cloud: displayEdition === 'cloud' })
+    .replace(/^---[\s\S]*?---\n\n<!--[^\n]+-->\n<!--[^\n]+-->\n/, '').trim());
   console.log(RULE);
 
   const a = await ask('\nInstall? [Y/n/skip] ');
@@ -192,12 +222,14 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
       writtenTo: [], declined: true,
       autoRefreshAgentFiles: false, autoInstallUpdates: false,
       lastRunVersion: VERSION,
+      ...setupStateFields(edition, accountId, readSetupState()),
     });
     console.log('Skipped. Run `sdoc setup` any time to revisit.');
     return;
   }
 
-  const result = syncAgentSkill({});
+  const existing = readSetupState();
+  const result = syncAgentSkill({ edition });
   const changed = syncChanged(result);
   if (changed || result.errors.length) printSyncSummary(result);
   if (result.errors.length) return;
@@ -212,6 +244,7 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
     autoRefreshAgentFiles: autoRefresh,
     autoInstallUpdates: autoInstall,
     lastRunVersion: VERSION,
+    ...setupStateFields(edition, accountId, existing),
   });
   console.log('\nDone. Run `sdoc setup` any time to revisit.');
 }
@@ -237,7 +270,7 @@ async function maybeAutoRefresh() {
     const next = implicitConsentState(toImplicitResults(result), VERSION);
     if (!next) return;
     printSyncSummary(result);
-    writeSetupState(next);
+    writeSetupState({ ...next, ...setupStateFields(null, null, null) });
     return;
   }
 
@@ -271,6 +304,7 @@ async function runRefresh() {
     autoRefreshAgentFiles: existing ? existing.autoRefreshAgentFiles !== false : true,
     autoInstallUpdates: existing && existing.autoInstallUpdates != null ? existing.autoInstallUpdates : false,
     lastRunVersion: VERSION,
+    ...setupStateFields(null, null, existing),
   });
 }
 
@@ -304,4 +338,5 @@ module.exports = {
   runRefresh,
   runAutoUpdateSubcommand,
   maybeAutoRefresh,
+  cloudFirstSettings,
 };

package/lib/short-link.js

@@ -18,6 +18,35 @@ const { slugify } = require('../shared/sdocs-slugify.js');
 const { toBase64Url } = require('./url');
 const { DEFAULT_URL } = require('./constants');
 
+const PLACEMENT_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{3,31}$/;
+const PLACEMENT_SOURCES = new Set(['x', 'yt', 'youtube']);
+
+function normalizePlacementId(value) {
+  if (value == null || value === '') return '';
+  const placement = String(value).trim();
+  if (!PLACEMENT_RE.test(placement)) {
+    throw new Error('placement must be 4-32 letters, numbers, underscores, or hyphens');
+  }
+  return placement;
+}
+
+function buildAttributionQuery(sourceValue, placementValue) {
+  const source = String(sourceValue || '').trim().toLowerCase();
+  const placement = normalizePlacementId(placementValue);
+  if (placement && !PLACEMENT_SOURCES.has(source)) {
+    throw new Error('placement requires --source x, yt, or youtube');
+  }
+  const query = new URLSearchParams();
+  if (source) query.set('src', source);
+  if (placement) query.set('pid', placement);
+  return query.toString();
+}
+
+function assembleShortUrl(baseUrl, id, attributionQuery, fragmentParams) {
+  const sourceQuery = attributionQuery ? `?${attributionQuery}` : '';
+  return `${baseUrl}/s/${id}${sourceQuery}#${fragmentParams.toString()}`;
+}
+
 // The blob format (nonce(12) + ciphertext + tag(16)) matches the browser.
 function compressAndEncrypt(content) {
   const compressed = zlib.brotliCompressSync(Buffer.from(content, 'utf-8'), {
@@ -72,6 +101,8 @@ function uploadShortLink(ciphertextB64, baseUrl) {
 
 async function buildShortUrl(content, opts) {
   if (!content) throw new Error('short link requires file content');
+  opts = opts || {};
+  const attributionQuery = buildAttributionQuery(opts.source, opts.placement);
 
   // Mirror the hash-build's default-stripping so the encrypted payload is
   // identical to what the browser would encode.
@@ -95,11 +126,17 @@ async function buildShortUrl(content, opts) {
   if (opts.theme) params.set('theme', opts.theme);
   if (opts.section) params.set('sec', slugify(opts.section));
 
-  return `${baseUrl}/s/${id}#${params.toString()}`;
+  // Source attribution belongs in the query so the server can receive it. The
+  // encryption key stays after # and therefore never leaves the browser. The
+  // short-link id and encrypted payload are unchanged by this label.
+  return assembleShortUrl(baseUrl, id, attributionQuery, params);
 }
 
 module.exports = {
   compressAndEncrypt,
   uploadShortLink,
   buildShortUrl,
+  normalizePlacementId,
+  buildAttributionQuery,
+  assembleShortUrl,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs-dev",
-  "version": "1.18.0",
+  "version": "1.19.2",
   "description": "Open, share, and style markdown files from the terminal",
   "main": "bin/sdocs-dev.js",
   "bin": {