@minnovate/shadow-publisher 0.2.0 → 0.5.0

package/README.md

@@ -4,11 +4,18 @@ Publish an app's Git history to the serverless Git publishing backend.
 
 ```sh
 npm install -g @minnovate/shadow-publisher
-publisher --help
-publisher login
+publisher skills install     # adds the publisher's skills to Claude Code
 ```
 
-Needs Node 22.12 or later and git 2.46 or later on `PATH`. The package is one bundled file with no
-runtime dependencies.
+Then ask Claude Code to publish your app. Without Claude Code:
+
+```sh
+publisher login              # signs you in through your browser
+publisher init . --name my-app
+publisher sync               # after every change: saves it and publishes it; no git needed
+```
+
+Needs Node 22.12 or later and git 2.46 or later on `PATH`. The package is one bundled file, and the
+Claude Code skills beside it, with no runtime dependencies.
 
 Apache-2.0 licensed; see `LICENSE`.

package/dist/claude/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "shadow-publisher",
+  "owner": { "name": "Minnovate" },
+  "description": "The publisher's Claude Code skills: publish an app and keep it in sync, without git.",
+  "plugins": [
+    {
+      "name": "git-publisher",
+      "source": "./plugin",
+      "description": "Publish an app folder and keep it updated (\"publish my app\", \"save my changes\", \"get the latest version\")."
+    }
+  ]
+}

package/dist/claude/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "git-publisher",
+  "displayName": "Git Publisher",
+  "version": "0.5.0",
+  "description": "Publish an app folder's Git history to the serverless Git publishing backend and keep it updated (\"publish my app\", \"update my app\", \"fetch the engineered version\").",
+  "author": { "name": "git-publisher project" },
+  "keywords": ["git", "publish", "deploy", "serverless"]
+}

package/dist/claude/plugin/README.md

@@ -0,0 +1,16 @@
+# Git Publisher plugin for Claude Code
+
+Thin adapter: two skills (`publish-app`, `sync-app`) that drive the `publisher` CLI
+(`@minnovate/shadow-publisher`, `packages/cli`) from PATH. All publication, retry, resume and merge
+logic lives in the shared client library; the skills only orchestrate, and a creator's changes are
+saved and published with `publisher sync`, never with git.
+
+It ships inside the npm package, and `publisher skills install` installs it into Claude Code.
+
+Runtime requirements in the environment where Claude Code runs: the publisher installed
+(`npm install -g @minnovate/shadow-publisher`, Node.js 22), Git ≥ 2.46 on PATH, outbound HTTPS to
+the portal's domain (sign-in and publishing at `/publish`) and the S3 bucket host for direct
+uploads/downloads.
+
+See `integrations/claude/README.md` for installation, authentication, uninstall and the verified
+environments.

package/dist/claude/plugin/skills/publish-app/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: publish-app
+description: Publish or update the user's app (a folder) with the publisher. Use when the user says "publish my app", "update my app", "save my changes", "push my changes", "save this version online", or asks to resolve an interrupted publication. Handles first-time setup, every later update, interruption recovery and conflicts by running the `publisher` command; never uses git to commit or push.
+allowed-tools: Bash(publisher *), Bash(git status *), Bash(git diff *), Bash(git log *)
+---
+
+# Publish or update the user's app
+
+You publish the user's app folder with the `publisher` command. All saving, merging, publishing,
+retry and resume logic lives in it; your job is to run it, read its `--json` output, and tell the
+user what happened in plain language. Never explain S3, packs, commits, sessions or tokens.
+
+**`publisher sync` is how a change is saved and published. Never run `git add`, `git commit`,
+`git push` or `git stash` in the user's app folder**, and never add a git remote. `sync` records the
+folder's changes itself — and leaves out `.env` files, keys, `node_modules` and anything larger than
+50 MB, which a hand-made commit would not. You may read with `git status`, `git diff` and `git log`
+to describe a change; nothing else.
+
+Every command accepts `--json` and prints exactly one JSON object on stdout. Exit codes:
+`0` success · `1` local/usage error · `2` rejected or conflict · `3` outcome not yet known · `4` authentication.
+
+## 1. Preflight (run once)
+
+```bash
+publisher --version
+```
+
+If the command is not found, tell the user the publisher is not installed and that one command
+installs it: `npm install -g @minnovate/shadow-publisher` (it needs Node.js 22). Stop there.
+
+```bash
+publisher doctor --json
+```
+
+- `gitOk:false` → tell the user Git 2.46 or later must be installed; stop.
+- Otherwise do exactly what **`next.action`** says. `doctor` works this out for you, and the same
+  `next` object rides on `error.details` of any command that cannot resolve a connection — so you
+  never have to interpret `credentials`, `endpoint` or `profiles` yourself.
+
+| `next.action` | What it means | What to do |
+|---|---|---|
+| `"ready"` | Signed in and pointed somewhere. | **Nothing. Go to step 2 and do not mention any of this.** |
+| `"sign-in"` | Not connected to anything yet. | **Ask them nothing** — `next.ask` is `null`. Just run `next.command` (`publisher login --json`). It finds the service, opens their browser and prints a code for them to confirm; tell them to expect that, and wait. Use `--portal <url>` only if they say they are on a different platform. |
+| `"choose-profile"` | Several places are set up and none is marked usual. | Show `next.profiles` and ask `next.ask`. Then run `next.command` with the name they picked. |
+| `"reauthenticate"` | The place is known; the credential is gone or expired. | Just run `next.command`. `next.ask` is `null` — do **not** ask them for anything; the browser sign-in asks them itself. |
+| `"bind-endpoint"` | A token is set in the environment, but nothing said where it may go. | **Stop** and tell them publishing is blocked by a token set in this shell. `next.command` is `null` on purpose: never set `GIT_PUBLISHER_ENDPOINT` or pass `--endpoint` yourself — that is exactly the choice the check leaves to whoever set the token. |
+
+**Never ask the user for a token, an endpoint, a URL or a credential — in any words.** They are
+publishing an app; they do not know what those are, and you no longer need them: `login` discovers
+where publishing lives and signs them in through their browser. `next.ask` is `null` whenever
+nothing needs asking, which is now every case except choosing between connections they already
+have; when it is not null it is already phrased for them, so pass it on rather than rewriting it.
+
+If they name an environment ("publish to dev"), pass `--profile dev` on each command rather than
+changing their default.
+
+## 2. First publication of a folder
+
+Run in the app folder (the folder the user is working in):
+
+```bash
+publisher info --json            # exit 1 with LOCAL_STATE "not associated" means: not published yet
+```
+
+If not associated:
+
+```bash
+publisher init . --name "<app name>" --json
+```
+
+`init` prepares the folder with an explicit file selection: it excludes `.git`, `node_modules`,
+build caches, `.env*`, keys/certificates and files larger than 50 MB, and it respects
+`.gitignore`. Show the user the `onboarding.excluded` list so they know what was left out (the
+exclusion rules are a safety net, not a secret scanner). Then publish it with step 3.
+
+## 3. Every update — and the first publish after `init`
+
+```bash
+publisher sync . --message "<a few words on what changed>" --json
+```
+
+That one command records what changed in the folder, brings in anything published meanwhile (a
+fast-forward or a clean merge — it never rewrites the user's work), and publishes the result. Write
+the message in the user's words ("Add a contact page"), not git's.
+
+## 4. Reading the result
+
+`state` says what happened; `hint` is one sentence you may pass on as it is.
+
+- `"published"` → the app was published. Mention what was recorded (`recorded.committed`) and, if
+  `recorded.excluded` is not empty, what was left out and why. Then tell them the portal shows the
+  app moving through **received → checked → going live → live**, and that it appears there within
+  a few minutes. (The publisher cannot follow those steps from here yet.)
+- `"up_to_date"` → nothing new to publish; the service already has this version.
+- `"conflict"` → the user's change and a published change touched the same lines of
+  `conflicts[]`. **Nothing was published and nothing was lost.** Do not resolve it on your own and
+  never publish with `--force`. Follow the `sync-app` skill's conflict section.
+- `"rejected"` with `publication.rejection.code`:
+  - `NON_FAST_FORWARD` / `STALE_GENERATION` / `EXPECTED_OLD_MISMATCH`: somebody published in the
+    moment between the merge and the publish. Run `publisher sync . --json` once more
+    (`publication.next.command` says the same).
+  - `REF_FORBIDDEN`: the user may not publish this branch; tell them which branch and stop.
+  - `MISSING_OBJECTS`: the local copy is incomplete (for example a shallow clone). Tell the user to
+    publish from a complete copy: `publisher checkout <new folder> --repo <id>`.
+  - `LIMIT_EXCEEDED`, `PACK_INVALID`: quote the message; suggest removing very large files from the
+    folder if the message mentions size.
+- `"unknown"` / exit code 3: the publication was sent but its outcome is not known yet. Run
+  `publisher status . --json`; it waits for and resolves interrupted publications without creating
+  duplicates. Repeat once if it still says `finalizing`.
+- Exit code 4: run `publisher doctor --json` and follow `next.action` (normally `reauthenticate`:
+  run `next.command`). Never ask the user for a token.
+
+## 5. Interrupted earlier?
+
+If a previous publish was interrupted (network loss, closed session), `publisher status . --json`
+resumes or resolves it. Always run it before starting a new sync when the last result was unknown.
+
+## Rules
+
+- `publisher sync` is the only way a change is saved and published. Never `git add`, `git commit`,
+  `git push`, `git stash`, `git reset`, `git rebase`, and never modify remotes.
+- Never print tokens or signed URLs. The publisher already redacts them.
+- Never publish with `--force` unless the user explicitly asks to overwrite the published history
+  and understands the other side's changes will be discarded.

package/dist/claude/plugin/skills/sync-app/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sync-app
+description: Bring the published (possibly engineered) version of the user's app into their folder, together with their own changes, and publish the result. Use when the user says "get the latest version", "sync my app", "sync with the engineering changes", when a publish was refused because somebody else published first, or when a sync reported a conflict. Never overwrites local work and never uses git to commit.
+allowed-tools: Bash(publisher *), Bash(git status *), Bash(git log *), Bash(git diff *)
+---
+
+# Keep the user's app in step with what is published
+
+**`publisher sync` does all of it**: it records the user's changes, brings in what was published
+meanwhile (a fast-forward, or a clean merge that never rewrites their work), and publishes the
+result. Never run `git add`, `git commit`, `git push`, `git pull`, `git merge`, `git stash`,
+`git reset` or `git rebase` in the user's app folder.
+
+```bash
+publisher sync . --json
+```
+
+Read `state` exactly as the `publish-app` skill describes (step 4). `merged` says whether anything
+published elsewhere was brought in (`"fast-forward"` or `"merge"`); mention it when it is not null.
+
+## Just looking
+
+To say where the folder stands without changing anything:
+
+```bash
+publisher workspace-status . --json      # state + hint; exit 2 means conflict
+```
+
+| state | meaning | what to do |
+| --- | --- | --- |
+| `up_to_date` | identical to the published version | nothing |
+| `local_changes` | the user changed something the service does not have yet | `publisher sync` |
+| `remote_ahead` | something was published elsewhere; the folder is behind | `publisher sync` |
+| `diverged_clean_merge` | both changed, and the changes combine cleanly | `publisher sync` |
+| `conflict` | both changed the same lines (`conflicts[]`) | see below |
+| `detached` | the folder is not on the branch it publishes | ask the user before anything else |
+
+`pending[]` lists interrupted publications; run `publisher status . --json` first when it is not empty.
+
+## A fresh copy
+
+When the user wants their app in a new folder (a new computer, a clean start):
+
+```bash
+publisher checkout <new-folder> --repo <repoId> --json   # a NEW folder only; refuses a non-empty one
+```
+
+## Conflicts
+
+A `conflict` means the user's version and the published one both changed the same lines of the
+files in `conflicts[]`. **Nothing was published and nothing was lost**: the user's change is
+recorded locally, and the published version is still on the service.
+
+1. List the files and say, in plain words, what each side changed there (`git diff` and `git log`
+   may help you describe it).
+2. Ask the user which version to keep for each file, or whether to combine them. Do not decide for
+   them and never publish with `--force` — that discards the other side's work.
+3. Only after they decide, put both versions into the files, marked:
+
+   ```bash
+   publisher sync . --mark-conflicts --json
+   ```
+
+   Each file in `conflicts[]` now holds both versions between `<<<<<<<`, `=======` and `>>>>>>>`
+   lines. Edit each to what they chose, and remove those lines.
+4. Run `publisher sync . --json`. It records the edit and publishes it. If a file still carries the
+   marker lines it refuses, names the files (`error.details.marked`) and publishes nothing; finish
+   the edit and run it again.
+
+No git command is needed at any point, including here.

package/dist/publisher.cjs

@@ -28,7 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/main.ts
-var import_node_path7 = require("node:path");
+var import_node_path8 = require("node:path");
 
 // ../protocol/src/versions.ts
 var PROTOCOL_VERSION = 1;
@@ -44,6 +44,7 @@ var PUBLICATION_ID_RE = new RegExp(`^pub_${ULID_BODY}$`);
 var CREATION_ID_RE = new RegExp(`^${ULID_BODY}$`);
 var TRANSACTION_ID_RE = new RegExp(`^(pub|cmp)_${ULID_BODY}$`);
 var PRINCIPAL_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._@-]{0,127}$/;
+var ORG_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 var SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 function ulid(now = Date.now()) {
   let time3 = now;
@@ -92,6 +93,10 @@ var ERROR_CODES = [
   "UNAUTHORIZED",
   "FORBIDDEN",
   "REF_FORBIDDEN",
+  // The credential names no organisation, so there is nothing to publish a repository FOR. Its own
+  // code rather than FORBIDDEN: a caller can act on it (sign in again, choosing an organisation),
+  // and a test that could not tell it from "you may not" would prove nothing about the check.
+  "ORGANISATION_REQUIRED",
   // repositories
   "REPOSITORY_NOT_FOUND",
   "REPOSITORY_CONFLICT",
@@ -133,6 +138,7 @@ var HTTP_STATUS_FOR_CODE = {
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   REF_FORBIDDEN: 403,
+  ORGANISATION_REQUIRED: 403,
   REPOSITORY_NOT_FOUND: 404,
   REPOSITORY_CONFLICT: 409,
   REPOSITORY_ARCHIVED: 409,
@@ -2585,6 +2591,7 @@ var PublicationId = string2().check(_regex(PUBLICATION_ID_RE));
 var TransactionId = string2().check(_regex(TRANSACTION_ID_RE));
 var CreationId = string2().check(_regex(CREATION_ID_RE));
 var PrincipalId = string2().check(_regex(PRINCIPAL_ID_RE));
+var OrgId = string2().check(_regex(ORG_ID_RE));
 var Sha256Hex = string2().check(_regex(SHA256_HEX_RE));
 var Oid = string2().check(_regex(/^[0-9a-f]{40}$|^[0-9a-f]{64}$/));
 var IsoDate = iso_exports.datetime({ offset: true });
@@ -2666,7 +2673,19 @@ var MetaRecord = object({
   objectFormat: ObjectFormat,
   createdAt: IsoDate,
   createdBy: PrincipalId,
-  creationId: CreationId
+  creationId: CreationId,
+  /**
+   * The organisation that published this repository, and what `repoId` is derived from: "that
+   * organisation publishes a repository" is the product's sentence.
+   *
+   * `null` is what a record written BEFORE repositories were org-scoped reads as, and every such
+   * record is still readable, cloneable and publishable — `tests/compat/fixtures/schema-v1` is one,
+   * and the promise that it stays readable is why this field is not required. What `null` must
+   * never do is default: the worker refuses to ANNOUNCE a publication it cannot attribute
+   * (`packages/worker/src/publish.ts`), because a consumer that guessed would create an
+   * application in an organisation nobody chose. Every repository created since carries one.
+   */
+  org: _default(nullable(OrgId), null)
 });
 var GrantPattern = string2().check(
   _minLength(1),
@@ -3971,6 +3990,47 @@ async function noteAcceptedPublication(directory, outcome, now = /* @__PURE__ */
   if (!oid) return;
   await advanceWorkspaceBase(directory, { oid, generation: outcome.resultGeneration }, now);
 }
+async function adoptWorkspace(client, directory, call = {}, now = /* @__PURE__ */ new Date()) {
+  const dir = (0, import_node_path3.resolve)(directory);
+  const existing = await getWorkspaceMapping(dir);
+  if (existing) return existing;
+  const section = await getConfigSection(dir, "publisher").catch(() => null);
+  const a = section ? associationFrom(section) : null;
+  if (!a) throw new PublisherError("LOCAL_STATE", "this folder is not associated with a published repository; run init first");
+  const branch = (await currentBranch(dir))?.replace(/^refs\/heads\//, "") ?? null;
+  if (!branch) throw new PublisherError("LOCAL_STATE", "HEAD is detached; check out the branch this folder publishes, then run sync again");
+  const repo = await client.getRepository(a.repoId, call);
+  const remoteOid = repo.refs[`refs/heads/${branch}`] ?? null;
+  const tip = await revParse(dir, `refs/heads/${branch}`);
+  let baseOid = null;
+  let baseGeneration = 0;
+  if (remoteOid) {
+    if (!await objectExists(dir, remoteOid)) await client.fetch({ repoDir: dir, repoId: a.repoId, remote: a.remote }, call);
+    const haveRemote = await objectExists(dir, remoteOid);
+    if (!tip) {
+      baseOid = haveRemote ? remoteOid : null;
+      baseGeneration = haveRemote ? repo.generation : 0;
+    } else if (haveRemote && (remoteOid === tip || await isAncestor(dir, remoteOid, tip))) {
+      baseOid = remoteOid;
+      baseGeneration = repo.generation;
+    } else if (haveRemote) {
+      const r = await runGit(["merge-base", tip, remoteOid], { cwd: dir, allowFailure: true });
+      const shared = r.code === 0 ? r.stdout.toString("utf8").trim() : "";
+      baseOid = shared === "" ? null : shared;
+    }
+  }
+  await writeMapping(dir, {
+    endpoint: a.endpoint,
+    repoId: a.repoId,
+    remote: a.remote,
+    branch,
+    baseOid,
+    baseGeneration,
+    checkedOutAt: now.toISOString(),
+    baseAdvancedAt: now.toISOString()
+  });
+  return await getWorkspaceMapping(dir);
+}
 async function isEmptyDir(p) {
   try {
     return (await (0, import_promises4.readdir)(p)).length === 0;
@@ -4065,7 +4125,16 @@ async function inspectWorkspace(client, directory, call = {}) {
   const dir = (0, import_node_path3.resolve)(directory);
   const mapping = await getWorkspaceMapping(dir);
   const pending = await listPending(dir).catch(() => []);
-  if (!mapping) return { state: "unassociated", mapping: null, local: null, remote: null, pending, conflicts: [], hint: "not a workspace; run checkout" };
+  if (!mapping)
+    return {
+      state: "unassociated",
+      mapping: null,
+      local: null,
+      remote: null,
+      pending,
+      conflicts: [],
+      hint: "not a workspace yet; run sync here (an associated folder adopts itself), or checkout to create one"
+    };
   const branchRef = `refs/heads/${mapping.branch}`;
   const tip = await revParse(dir, branchRef);
   const head = await revParse(dir, "HEAD");
@@ -4088,27 +4157,31 @@ async function inspectWorkspace(client, directory, call = {}) {
     );
   }
   if (!remoteOid) {
-    if (!tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; commit, then publish` : "empty on both sides");
-    return done("local_changes", "the server has no such branch yet; publish to create it");
+    if (!tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; publisher sync records and publishes them` : "empty on both sides");
+    return done("local_changes", "the server has no such branch yet; publisher sync creates it");
   }
   if (!tip) return done("remote_ahead", hasLocalWork ? `local branch is unborn and there are ${work}; move them aside, then sync` : "local branch is unborn; sync to fast-forward");
   if (!await objectExists(dir, remoteOid)) {
     await client.fetch({ repoDir: dir, repoId: mapping.repoId, remote: mapping.remote }, call);
     if (!await objectExists(dir, remoteOid)) return done("remote_ahead", "server tip could not be fetched; retry");
   }
-  if (remoteOid === tip) return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; commit, then publish` : "in sync with the server");
+  if (remoteOid === tip)
+    return done(hasLocalWork ? "local_changes" : "up_to_date", hasLocalWork ? `${work}; publisher sync records and publishes them` : "in sync with the server");
   if (await isAncestor(dir, remoteOid, tip))
-    return done("local_changes", hasLocalWork ? `local commits and ${work}; commit, then publish` : "local commits not yet published; publish");
+    return done(
+      "local_changes",
+      hasLocalWork ? `local commits and ${work}; publisher sync records and publishes them` : "local commits not yet published; publisher sync publishes them"
+    );
   if (await isAncestor(dir, tip, remoteOid))
     return done(
       "remote_ahead",
-      hasLocalWork ? `server moved ahead and there are ${work}; commit or stash them, then sync to fast-forward` : "server moved ahead; sync to fast-forward"
+      hasLocalWork ? `server moved ahead and there are ${work}; publisher sync records them, brings the server's changes in and publishes` : "server moved ahead; publisher sync brings it in"
     );
   const merge2 = await mergeRemote({ repoDir: dir, ours: branchRef, theirs: remoteOid, apply: false });
   if (merge2.ok)
     return done(
       "diverged_clean_merge",
-      hasLocalWork ? `both sides changed, merge is clean; commit or stash the ${work}, then sync --apply` : "both sides changed, merge is clean; sync --apply, then publish"
+      hasLocalWork ? `both sides changed, merge is clean; publisher sync records the ${work}, merges and publishes` : "both sides changed, merge is clean; publisher sync merges and publishes"
     );
   return done(
     "conflict",
@@ -4118,6 +4191,7 @@ async function inspectWorkspace(client, directory, call = {}) {
 }
 async function syncWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new Date()) {
   const dir = (0, import_node_path3.resolve)(opts.directory);
+  await adoptWorkspace(client, dir, call, now);
   const before = await inspectWorkspace(client, dir, call);
   if (!before.mapping) throw new PublisherError("LOCAL_STATE", "not a workspace; run checkout");
   const mapping = before.mapping;
@@ -4125,7 +4199,7 @@ async function syncWorkspace(client, opts, call = {}, now = /* @__PURE__ */ new
   let applied = null;
   if (before.state === "detached") throw new PublisherError("LOCAL_STATE", before.hint);
   if (opts.apply && before.remote?.oid && (before.state === "remote_ahead" || before.state === "diverged_clean_merge")) {
-    if (before.local?.dirty) throw new PublisherError("LOCAL_STATE", "the working tree has uncommitted changes; commit or stash them before sync --apply");
+    if (before.local?.dirty) throw new PublisherError("LOCAL_STATE", "the working tree has uncommitted changes; record them first (publisher sync does)");
     if (!before.local?.tip) {
       await runGit(["checkout", "-q", "-B", mapping.branch, before.remote.oid], { cwd: dir });
       applied = "fast-forward";
@@ -4419,17 +4493,205 @@ async function updateEntry(url2, change) {
   await writeCredentials(file);
 }
 
+// ../client/src/onboard.ts
+var import_promises6 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
+var DEFAULT_EXCLUDED_DIRS = [
+  ".git",
+  "node_modules",
+  ".venv",
+  "venv",
+  "__pycache__",
+  ".cache",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".parcel-cache",
+  ".aws",
+  ".ssh",
+  ".gnupg",
+  ".idea",
+  ".terraform",
+  ".pytest_cache",
+  ".mypy_cache",
+  "coverage",
+  ".DS_Store"
+];
+var DEFAULT_EXCLUDED_FILES = [
+  /^\.env(\..*)?$/,
+  /\.(pem|key|p12|pfx|jks|keystore)$/i,
+  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+  /^\.npmrc$/,
+  /^\.pypirc$/,
+  /^\.netrc$/,
+  /\.(log|tmp|swp)$/i,
+  /^\.DS_Store$/,
+  /^Thumbs\.db$/i,
+  /^credentials(\.json)?$/i,
+  /^service-account.*\.json$/i,
+  /^\.git(modules|attributes)?$/
+];
+async function onboardFolder(opts) {
+  const dir = opts.dir;
+  const policy = opts.policy ?? {};
+  const maxBytes = policy.maxFileBytes ?? 50 * 1024 * 1024;
+  let initialized = false;
+  if (await isGitRepo(dir)) {
+    const head = await headCommit(dir);
+    if (head && !policy.allowExistingHistory) {
+      throw new PublisherError("LOCAL_STATE", "folder is already a Git repository with history; commit your changes and use publish instead of init");
+    }
+  } else {
+    await initWorkRepo(dir, opts.branch ?? "main");
+    initialized = true;
+  }
+  const excluded = [];
+  const candidates = [];
+  const extra = policy.exclude ?? [];
+  const walk = async (d) => {
+    for (const e of await (0, import_promises6.readdir)(d, { withFileTypes: true })) {
+      if (opts.signal?.aborted) throw new PublisherError("CANCELLED", "cancelled");
+      const full = (0, import_node_path5.join)(d, e.name);
+      const rel = (0, import_node_path5.relative)(dir, full).split(import_node_path5.sep).join("/");
+      if (e.isSymbolicLink()) {
+        excluded.push({ path: rel, reason: "symbolic link" });
+        continue;
+      }
+      if (e.isDirectory()) {
+        if (excludedDir(rel, e.name, extra)) {
+          excluded.push({ path: rel + "/", reason: "excluded by policy" });
+          continue;
+        }
+        await walk(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (excludedFile(rel, e.name, extra)) {
+        excluded.push({ path: rel, reason: "excluded by policy" });
+        continue;
+      }
+      const st = await (0, import_promises6.stat)(full);
+      if (st.size > maxBytes) {
+        excluded.push({ path: rel, reason: `larger than ${maxBytes} bytes` });
+        continue;
+      }
+      candidates.push(rel);
+    }
+  };
+  await walk(dir);
+  const ignored = await checkIgnore(dir, candidates);
+  const selected = candidates.filter((p) => !ignored.has(p)).sort();
+  for (const p of ignored) excluded.push({ path: p, reason: "ignored by .gitignore" });
+  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded, initialized };
+  const commit = await commitPaths(dir, selected, {
+    message: opts.message ?? "Initial publication",
+    ...opts.authorName ? { authorName: opts.authorName } : {},
+    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  return { repoDir: dir, commit, committed: selected, excluded, initialized };
+}
+function excludedDir(rel, name, extra) {
+  return DEFAULT_EXCLUDED_DIRS.includes(name) || extra.some((p) => matches(rel, name, p));
+}
+function excludedFile(rel, name, extra) {
+  return DEFAULT_EXCLUDED_FILES.some((re) => re.test(name)) || extra.some((p) => matches(rel, name, p));
+}
+async function recordChanges(opts) {
+  const dir = opts.dir;
+  if (!await isGitRepo(dir)) throw new PublisherError("LOCAL_STATE", "this folder is not published yet; run publisher init first");
+  const maxBytes = opts.policy?.maxFileBytes ?? 50 * 1024 * 1024;
+  const extra = opts.policy?.exclude ?? [];
+  const excluded = [];
+  const selected = [];
+  const entries = await statusPorcelain(dir);
+  if (await mergeInProgress(dir)) {
+    const marked = [];
+    for (const { code, path } of entries) {
+      if (!UNMERGED.has(code)) continue;
+      const text = await (0, import_promises6.readFile)((0, import_node_path5.join)(dir, path), "utf8").catch(() => "");
+      if (/^<{7} /m.test(text) && /^>{7} /m.test(text)) marked.push(path);
+    }
+    if (marked.length)
+      throw new PublisherError(
+        "LOCAL_STATE",
+        `still marked as conflicting: ${marked.join(", ")}; keep one version (or both) in each, remove the <<<<<<< ======= >>>>>>> lines, then sync again`,
+        { details: { marked } }
+      );
+  }
+  for (const { code, path } of entries) {
+    if (code !== "??") {
+      selected.push(path);
+      continue;
+    }
+    const parts = path.split("/");
+    const name = parts[parts.length - 1];
+    const dirs = parts.slice(0, -1);
+    const inExcludedDir = dirs.findIndex((d, i) => excludedDir(dirs.slice(0, i + 1).join("/"), d, extra));
+    if (inExcludedDir >= 0) {
+      excluded.push({ path: dirs.slice(0, inExcludedDir + 1).join("/") + "/", reason: "excluded by policy" });
+      continue;
+    }
+    if (excludedFile(path, name, extra)) {
+      excluded.push({ path, reason: "excluded by policy" });
+      continue;
+    }
+    const st = await (0, import_promises6.lstat)((0, import_node_path5.join)(dir, path));
+    if (st.isSymbolicLink()) {
+      excluded.push({ path, reason: "symbolic link" });
+      continue;
+    }
+    if (st.size > maxBytes) {
+      excluded.push({ path, reason: `larger than ${maxBytes} bytes` });
+      continue;
+    }
+    selected.push(path);
+  }
+  const unique = dedupe(excluded);
+  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded: unique, initialized: false };
+  const commit = await commitPaths(dir, selected.sort(), {
+    message: opts.message ?? "Update",
+    ...opts.authorName ? { authorName: opts.authorName } : {},
+    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
+    ...opts.signal ? { signal: opts.signal } : {}
+  });
+  return { repoDir: dir, commit, committed: selected, excluded: unique, initialized: false };
+}
+var UNMERGED = /* @__PURE__ */ new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
+async function mergeInProgress(dir) {
+  return (await runGit(["rev-parse", "-q", "--verify", "MERGE_HEAD"], { cwd: dir, allowFailure: true })).code === 0;
+}
+function dedupe(excluded) {
+  const seen = /* @__PURE__ */ new Set();
+  return excluded.filter((e) => seen.has(e.path) ? false : (seen.add(e.path), true));
+}
+function matches(rel, base, pattern) {
+  if (pattern.includes("*")) {
+    const re = new RegExp(
+      "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+    );
+    return re.test(base) || re.test(rel);
+  }
+  return base === pattern || rel === pattern || rel.startsWith(pattern.replace(/\/$/, "") + "/");
+}
+async function checkIgnore(dir, paths) {
+  if (paths.length === 0) return /* @__PURE__ */ new Set();
+  const r = await runGit(["check-ignore", "--stdin", "-z"], { cwd: dir, input: paths.join("\0") + "\0", allowFailure: true });
+  if (r.code !== 0) return /* @__PURE__ */ new Set();
+  return new Set(r.stdout.toString("utf8").split("\0").filter(Boolean));
+}
+
 // ../client/src/fetch.ts
 var import_node_fs5 = require("node:fs");
-var import_promises7 = require("node:fs/promises");
+var import_promises8 = require("node:fs/promises");
 var import_node_os3 = require("node:os");
-var import_node_path5 = require("node:path");
-var import_promises8 = require("node:stream/promises");
+var import_node_path6 = require("node:path");
+var import_promises9 = require("node:stream/promises");
 var import_node_stream2 = require("node:stream");
 var import_node_crypto4 = require("node:crypto");
 
 // ../client/src/publish.ts
-var import_promises6 = require("node:fs/promises");
+var import_promises7 = require("node:fs/promises");
 
 // ../client/src/transport.ts
 function assertCredentialEndpoint(endpoint) {
@@ -4614,7 +4876,7 @@ async function publish(ctx, repoId, remote, opts, call) {
       } catch (e) {
         if (!(e instanceof PublisherError && e.code === "LOCAL_STATE")) throw e;
       }
-      if (remaining.length === 0) return toOutcome(outcome, true);
+      if (remaining.length === 0) return toOutcome(outcome, true, pending2.refUpdates);
       return publish(ctx, repoId, remote, opts, call);
     }
   }
@@ -4690,7 +4952,7 @@ async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opt
   }
   if (opts.wait === false) {
     summary = summary ?? await ctx.getStatus(repoId, pending.publicationId, call);
-    return toOutcome(summary, resumed);
+    return toOutcome(summary, resumed, pending.refUpdates);
   }
   progress({ phase: "validate", message: "waiting for validation" });
   summary = await waitForOutcome(ctx, repoId, pending.publicationId, opts.waitTimeoutMs ?? 10 * 6e4, call);
@@ -4700,9 +4962,9 @@ async function runPublication(ctx, repoId, remote, repoDir, store2, pending, opt
     progress({ phase: "done", message: `published generation ${summary.resultGeneration}` });
   } else if (summary.state === "rejected") {
     await store2.remove(pending.publicationId);
-    if (pending.pack) await (0, import_promises6.rm)(pending.pack.path, { force: true });
+    if (pending.pack) await (0, import_promises7.rm)(pending.pack.path, { force: true });
   }
-  return toOutcome(summary, resumed);
+  return toOutcome(summary, resumed, pending.refUpdates);
 }
 async function waitForOutcome(ctx, repoId, publicationId, timeoutMs, call) {
   const deadline = Date.now() + timeoutMs;
@@ -4749,7 +5011,7 @@ async function resolvePending(ctx, repoDir, remote, pending, call, store2) {
   }
   return summary;
 }
-function toOutcome(s, resumed) {
+function toOutcome(s, resumed, updates) {
   return {
     publicationId: s.publicationId,
     repoId: s.repoId,
@@ -4758,10 +5020,23 @@ function toOutcome(s, resumed) {
     resultGeneration: s.resultGeneration,
     refs: s.refs,
     rejection: s.rejection,
+    next: publishNext(s.rejection, updates[0]?.ref ?? null),
     resumed,
     summary: s
   };
 }
+var REF_MOVED = /* @__PURE__ */ new Set(["NON_FAST_FORWARD", "EXPECTED_OLD_MISMATCH", "STALE_GENERATION"]);
+function publishNext(rejection, published) {
+  if (rejection === null || !REF_MOVED.has(rejection.code)) return null;
+  const named = rejection.details?.["ref"];
+  const ref = typeof named === "string" ? named : published;
+  const name = ref?.replace(/^refs\/heads\//, "") ?? "main";
+  return {
+    action: "sync-and-publish",
+    ask: `${name} moved since your last fetch: someone else published to it. Sync brings those changes in without rewriting yours, and publishes the result.`,
+    command: `publisher sync`
+  };
+}
 async function defaultUpdate(repoDir) {
   const branch = await currentBranch(repoDir);
   if (!branch) throw new PublisherError("LOCAL_STATE", "detached HEAD: specify which ref to publish");
@@ -4807,15 +5082,15 @@ function trackingRef(remote, ref) {
 // ../client/src/fetch.ts
 async function installedManifest(gd) {
   try {
-    const parsed = JSON.parse(await (0, import_promises7.readFile)((0, import_node_path5.join)(gd, "publisher", "installed.json"), "utf8"));
+    const parsed = JSON.parse(await (0, import_promises8.readFile)((0, import_node_path6.join)(gd, "publisher", "installed.json"), "utf8"));
     return new Set(Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : []);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
 async function writeManifest(gd, installed) {
-  await (0, import_promises7.mkdir)((0, import_node_path5.join)(gd, "publisher"), { recursive: true });
-  await (0, import_promises7.writeFile)((0, import_node_path5.join)(gd, "publisher", "installed.json"), JSON.stringify(installed));
+  await (0, import_promises8.mkdir)((0, import_node_path6.join)(gd, "publisher"), { recursive: true });
+  await (0, import_promises8.writeFile)((0, import_node_path6.join)(gd, "publisher", "installed.json"), JSON.stringify(installed));
 }
 async function fetchRepository(ctx, repoId, opts, call) {
   const remote = opts.remote ?? "publisher";
@@ -4862,13 +5137,14 @@ async function haveAll(repoDir, refs) {
 async function install(ctx, gd, artifacts, call) {
   if (artifacts.length === 0) return 0;
   const progress = call.onProgress ?? (() => void 0);
-  const tmp = await (0, import_promises7.mkdtemp)((0, import_node_path5.join)((0, import_node_os3.tmpdir)(), "gitpub-fetch-"));
+  const tmp = await (0, import_promises8.mkdtemp)((0, import_node_path6.join)((0, import_node_os3.tmpdir)(), "gitpub-fetch-"));
   let bytes = 0;
+  const total = artifacts.reduce((sum, a) => sum + a.size, 0);
   try {
     for (const a of artifacts) {
-      const file = (0, import_node_path5.join)(tmp, `${a.sha256}.${a.kind}`);
+      const file = (0, import_node_path6.join)(tmp, `${a.sha256}.${a.kind}`);
       bytes += await download(ctx.fetchImpl, a.url, file, a.sha256, a.size, call);
-      progress({ phase: "fetch", message: `installing ${a.kind}`, bytes, total: a.size });
+      progress({ phase: "fetch", message: `installing ${a.kind}`, bytes, total });
       if (a.kind === "bundle") {
         await bundleUnbundleObjects(gd, file);
       } else {
@@ -4876,7 +5152,7 @@ async function install(ctx, gd, artifacts, call) {
       }
     }
   } finally {
-    await (0, import_promises7.rm)(tmp, { recursive: true, force: true });
+    await (0, import_promises8.rm)(tmp, { recursive: true, force: true });
   }
   return bytes;
 }
@@ -4916,7 +5192,7 @@ async function download(fetchImpl, url2, dest, sha256, size, call) {
       controller.enqueue(chunk);
     }
   });
-  await (0, import_promises8.pipeline)(import_node_stream2.Readable.fromWeb(res.body.pipeThrough(counted)), (0, import_node_fs5.createWriteStream)(dest));
+  await (0, import_promises9.pipeline)(import_node_stream2.Readable.fromWeb(res.body.pipeThrough(counted)), (0, import_node_fs5.createWriteStream)(dest));
   if (n !== size || hash.digest("hex") !== sha256) throw new PublisherError("NETWORK", "downloaded artifact failed checksum verification", { retryable: true });
   return n;
 }
@@ -4924,6 +5200,11 @@ async function download(fetchImpl, url2, dest, sha256, size, call) {
 // ../client/src/publisher.ts
 var CLIENT_NAME = "git-publisher-client";
 var CLIENT_VERSION = "0.1.0";
+async function markConflicts(dir, remote) {
+  const who = { GIT_AUTHOR_NAME: "Publisher", GIT_AUTHOR_EMAIL: "publisher@localhost", GIT_COMMITTER_NAME: "Publisher", GIT_COMMITTER_EMAIL: "publisher@localhost" };
+  const r = await runGit(["merge", "--no-ff", "--no-commit", "--no-verify", remote], { cwd: dir, env: { extra: who }, allowFailure: true });
+  if (r.code !== 0 && !await mergeInProgress(dir)) throw new PublisherError("GIT", `could not mark the conflicts: ${r.stderr.trim()}`);
+}
 var Publisher = class {
   constructor(opts) {
     this.opts = opts;
@@ -5022,6 +5303,10 @@ var Publisher = class {
   async checkout(options, call = {}) {
     return checkoutWorkspace(this, options, call);
   }
+  /** Make an associated folder a workspace (idempotent); `init` and `sync` both call it. */
+  async adoptWorkspace(directory, call = {}) {
+    return adoptWorkspace(this, directory, call);
+  }
   /** Offline: the persisted workspace mapping, or null. */
   async workspace(directory) {
     return getWorkspaceMapping(directory);
@@ -5034,6 +5319,37 @@ var Publisher = class {
   async sync(options, call = {}) {
     return syncWorkspace(this, options, call);
   }
+  /**
+   * A creator's whole round trip in one call, so nobody runs git: record their changes, bring in
+   * what the service has (fast-forward or a clean merge, never a rewrite), and publish. It stops,
+   * having published nothing, on a conflict; the recorded commit stays, so nothing is lost.
+   *
+   * Everything that can refuse without touching the folder refuses first: a folder with no
+   * association (or one pinned elsewhere) and a HEAD off the workspace branch would otherwise get
+   * a commit and then an error. `syncWorkspace` itself still never commits or publishes; this is
+   * the composition, and the only one.
+   */
+  async syncChanges(options, call = {}) {
+    const dir = options.directory;
+    await this.resolveRepo(dir);
+    const branch = (await currentBranch(dir))?.replace(/^refs\/heads\//, "") ?? null;
+    if (!branch) throw new PublisherError("LOCAL_STATE", "HEAD is detached; check out the branch this folder publishes, then run sync again");
+    const mapped = await getWorkspaceMapping(dir);
+    if (mapped && mapped.branch !== branch)
+      throw new PublisherError("LOCAL_STATE", `branch ${branch} is checked out, but this folder publishes ${mapped.branch}; check it out, then run sync again`);
+    const recorded = await recordChanges({ dir, ...options.message ? { message: options.message } : {} });
+    const reconciled = await syncWorkspace(this, { directory: dir, apply: true }, call);
+    const base = { recorded: { commit: recorded.commit, committed: recorded.committed, excluded: recorded.excluded }, reconciled };
+    if (reconciled.after === "conflict") {
+      const remote = reconciled.before.remote?.oid ?? null;
+      if (options.markConflicts && remote) await markConflicts(dir, remote);
+      return { ...base, state: "conflict", published: null, marked: options.markConflicts === true && remote !== null };
+    }
+    const tip = await revParse(dir, `refs/heads/${branch}`);
+    if (tip === null || tip === (reconciled.before.remote?.oid ?? null)) return { ...base, state: "up_to_date", published: null, marked: false };
+    const published = await this.publish({ repoDir: dir }, call);
+    return { ...base, state: published.state === "accepted" ? "published" : published.state === "rejected" ? "rejected" : "unknown", published, marked: false };
+  }
   /** Resolve interrupted publications recorded locally without creating duplicates. */
   async resumePublications(repoDir, call = {}) {
     const { remote } = await this.resolveRepo(repoDir);
@@ -5051,7 +5367,7 @@ var Publisher = class {
         call.onProgress?.({ phase: "validate", message: `waiting for ${p.publicationId}` });
         s = await resolvePending(this.publishContext(), repoDir, remote, p, { ...call, waitSeconds: MAX_WAIT_SECONDS }, store2);
       }
-      out.push(toOutcome(s, true));
+      out.push(toOutcome(s, true, p.refUpdates));
     }
     for (const o of out) await noteAcceptedPublication(repoDir, o);
     return out;
@@ -5087,120 +5403,6 @@ function createPublisher(opts) {
   return new Publisher(opts);
 }
 
-// ../client/src/onboard.ts
-var import_promises9 = require("node:fs/promises");
-var import_node_path6 = require("node:path");
-var DEFAULT_EXCLUDED_DIRS = [
-  ".git",
-  "node_modules",
-  ".venv",
-  "venv",
-  "__pycache__",
-  ".cache",
-  ".next",
-  ".nuxt",
-  ".turbo",
-  ".parcel-cache",
-  ".aws",
-  ".ssh",
-  ".gnupg",
-  ".idea",
-  ".terraform",
-  ".pytest_cache",
-  ".mypy_cache",
-  "coverage",
-  ".DS_Store"
-];
-var DEFAULT_EXCLUDED_FILES = [
-  /^\.env(\..*)?$/,
-  /\.(pem|key|p12|pfx|jks|keystore)$/i,
-  /^id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
-  /^\.npmrc$/,
-  /^\.pypirc$/,
-  /^\.netrc$/,
-  /\.(log|tmp|swp)$/i,
-  /^\.DS_Store$/,
-  /^Thumbs\.db$/i,
-  /^credentials(\.json)?$/i,
-  /^service-account.*\.json$/i,
-  /^\.git(modules|attributes)?$/
-];
-async function onboardFolder(opts) {
-  const dir = opts.dir;
-  const policy = opts.policy ?? {};
-  const maxBytes = policy.maxFileBytes ?? 50 * 1024 * 1024;
-  let initialized = false;
-  if (await isGitRepo(dir)) {
-    const head = await headCommit(dir);
-    if (head && !policy.allowExistingHistory) {
-      throw new PublisherError("LOCAL_STATE", "folder is already a Git repository with history; commit your changes and use publish instead of init");
-    }
-  } else {
-    await initWorkRepo(dir, opts.branch ?? "main");
-    initialized = true;
-  }
-  const excluded = [];
-  const candidates = [];
-  const extra = policy.exclude ?? [];
-  const walk = async (d) => {
-    for (const e of await (0, import_promises9.readdir)(d, { withFileTypes: true })) {
-      if (opts.signal?.aborted) throw new PublisherError("CANCELLED", "cancelled");
-      const full = (0, import_node_path6.join)(d, e.name);
-      const rel = (0, import_node_path6.relative)(dir, full).split(import_node_path6.sep).join("/");
-      if (e.isSymbolicLink()) {
-        excluded.push({ path: rel, reason: "symbolic link" });
-        continue;
-      }
-      if (e.isDirectory()) {
-        if (DEFAULT_EXCLUDED_DIRS.includes(e.name) || extra.some((p) => matches(rel, e.name, p))) {
-          excluded.push({ path: rel + "/", reason: "excluded by policy" });
-          continue;
-        }
-        await walk(full);
-        continue;
-      }
-      if (!e.isFile()) continue;
-      if (DEFAULT_EXCLUDED_FILES.some((re) => re.test(e.name)) || extra.some((p) => matches(rel, e.name, p))) {
-        excluded.push({ path: rel, reason: "excluded by policy" });
-        continue;
-      }
-      const st = await (0, import_promises9.stat)(full);
-      if (st.size > maxBytes) {
-        excluded.push({ path: rel, reason: `larger than ${maxBytes} bytes` });
-        continue;
-      }
-      candidates.push(rel);
-    }
-  };
-  await walk(dir);
-  const ignored = await checkIgnore(dir, candidates);
-  const selected = candidates.filter((p) => !ignored.has(p)).sort();
-  for (const p of ignored) excluded.push({ path: p, reason: "ignored by .gitignore" });
-  if (selected.length === 0) return { repoDir: dir, commit: null, committed: [], excluded, initialized };
-  const commit = await commitPaths(dir, selected, {
-    message: opts.message ?? "Initial publication",
-    ...opts.authorName ? { authorName: opts.authorName } : {},
-    ...opts.authorEmail ? { authorEmail: opts.authorEmail } : {},
-    ...opts.signal ? { signal: opts.signal } : {}
-  });
-  return { repoDir: dir, commit, committed: selected, excluded, initialized };
-}
-function matches(rel, base, pattern) {
-  if (pattern.includes("*")) {
-    const re = new RegExp(
-      "^" + pattern.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
-    );
-    return re.test(base) || re.test(rel);
-  }
-  return base === pattern || rel === pattern || rel.startsWith(pattern.replace(/\/$/, "") + "/");
-}
-async function checkIgnore(dir, paths) {
-  if (paths.length === 0) return /* @__PURE__ */ new Set();
-  const r = await runGit(["check-ignore", "--stdin", "-z"], { cwd: dir, input: paths.join("\0") + "\0", allowFailure: true });
-  if (r.code !== 0) return /* @__PURE__ */ new Set();
-  return new Set(r.stdout.toString("utf8").split("\0").filter(Boolean));
-}
-
 // ../client/src/migrate.ts
 async function fetchCapabilities(endpoint, fetchImpl = fetch, signal) {
   const res = await fetchImpl(`${normalize(endpoint)}/v1/capabilities`, { method: "GET", ...signal ? { signal } : {} });
@@ -5420,7 +5622,9 @@ var OPTIONS = {
   quiet: { type: "boolean" },
   force: { type: "boolean" },
   apply: { type: "boolean" },
+  "mark-conflicts": { type: "boolean" },
   help: { type: "boolean" },
+  version: { type: "boolean" },
   "set-default": { type: "boolean" },
   // A flag of its own, not a negation of --wait: there is no --wait.
   "no-wait": { type: "boolean" }
@@ -5434,10 +5638,67 @@ function parseArgs(argv) {
   }
 }
 
+// src/skills.ts
+var import_node_child_process3 = require("node:child_process");
+var import_node_fs6 = require("node:fs");
+var import_node_path7 = require("node:path");
+var MARKETPLACE = "shadow-publisher";
+var PLUGIN = "git-publisher";
+function packageRoot() {
+  return (0, import_node_path7.join)((0, import_node_path7.dirname)((0, import_node_fs6.realpathSync)(process.argv[1])), "..");
+}
+function packageVersion() {
+  try {
+    return JSON.parse((0, import_node_fs6.readFileSync)((0, import_node_path7.join)(packageRoot(), "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+function claude(args) {
+  return new Promise((resolve3) => {
+    let stdout = "";
+    let stderr = "";
+    const child = (0, import_node_child_process3.spawn)("claude", args, { stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", (d) => stdout += d.toString("utf8"));
+    child.stderr.on("data", (d) => stderr += d.toString("utf8"));
+    child.on("error", (e) => resolve3({ code: null, stdout, stderr: e.message, missing: e.code === "ENOENT" }));
+    child.on("close", (code) => resolve3({ code, stdout, stderr, missing: false }));
+  });
+}
+async function installSkills({ log }) {
+  const source = (0, import_node_path7.join)(packageRoot(), "dist", "claude");
+  if (!(0, import_node_fs6.existsSync)((0, import_node_path7.join)(source, ".claude-plugin", "marketplace.json"))) {
+    throw new PublisherError("LOCAL_STATE", `this publisher carries no skills at ${source}; reinstall it with: npm install -g @minnovate/shadow-publisher`);
+  }
+  const step = async (what, args) => {
+    log(what);
+    const r = await claude(args);
+    if (r.missing) {
+      throw new PublisherError(
+        "LOCAL_STATE",
+        'Claude Code is not installed, or "claude" is not on PATH. Install it from https://claude.com/claude-code, then run: publisher skills install'
+      );
+    }
+    if (r.code !== 0) throw new PublisherError("LOCAL_STATE", `"claude ${args.slice(0, 3).join(" ")}" failed: ${(r.stderr || r.stdout).trim()}`);
+  };
+  await step("Adding the publisher to Claude Code\u2026", ["plugin", "marketplace", "add", source, "--scope", "user"]);
+  await step("Installing its skills\u2026", ["plugin", "install", `${PLUGIN}@${MARKETPLACE}`, "--scope", "user"]);
+  return {
+    ok: true,
+    plugin: `${PLUGIN}@${MARKETPLACE}`,
+    marketplace: MARKETPLACE,
+    source,
+    version: packageVersion(),
+    message: "The publisher skills are installed in Claude Code for your user. Start a new Claude Code session (or run /reload-plugins in an open one) and ask it to publish your app."
+  };
+}
+
 // src/main.ts
 var USAGE = `publisher \u2014 publish an app's Git history to the serverless Git backend
 
 Usage:
+  publisher skills install                              add the publisher's skills to Claude Code (user scope);
+                                                        run it again after updating the publisher
   publisher login                                       sign in. With NO arguments it asks the
                                                         portal where publishing lives, opens a
                                                         browser to confirm who you are, and asks
@@ -5447,19 +5708,29 @@ Usage:
       [--profile <name>] [--set-default] [--token <token>]
   publisher logout (--endpoint <url> | --profile <name>)
   publisher profile list | profile use <name> | profile remove <name>
-  publisher init [dir] [--name <name>] [--repo <id>]    create (or attach to) a repository and associate this folder
-  publisher publish [dir] [--ref <ref>]... [--force] [--no-wait]
+  publisher init [dir] [--name <name>] [--repo <id>]    create (or attach to) a repository, associate this folder
+                                                        and record it as a workspace (so sync works here)
+  publisher publish [dir] [--ref <ref>]... [--force] [--no-wait]   publish commits as they are; to save and publish
+                                                        a change, use sync
   publisher status [dir] [--publication <id>]           resolve pending/interrupted publications
   publisher fetch [dir]
   publisher checkout <dir> --repo <id> [--branch <name>]  create a NEW editable workspace (never overlays a folder)
   publisher workspace-status [dir]                      offline mapping + where the workspace stands (real three-way check)
-  publisher sync [dir] [--apply]                         fetch; with --apply fast-forward or merge cleanly, advance the base
+  publisher sync [dir] [--message <text>]               THE way to save and publish a change: records the folder's
+                                                        changes (never .env, keys or node_modules), brings in what
+                                                        was published meanwhile (fast-forward or a clean merge,
+                                                        never a rewrite) and publishes. Stops on a conflict with
+                                                        nothing published and nothing lost. No git needed
+      [--mark-conflicts]                                on a conflict, put both versions in each file, marked,
+                                                        to edit; the next sync records and publishes the edit
   publisher merge-check [dir] --ours <ref> --theirs <ref> [--apply]
   publisher info [dir]                                   repository state as seen by the server
   publisher doctor                                       environment check (node, git, credentials, association)
   publisher migrate [dir] [--to <url>]                   re-point a folder whose service moved (asks the service where)
 
-Global flags: --endpoint <url>, --profile <name>, --token, --json, --quiet
+Global flags: --endpoint <url>, --profile <name>, --token, --json, --quiet, --version
+
+A creator never needs git: init once, then sync after every change.
 
 Which endpoint a command uses, first hit wins:
   --endpoint <url>              an explicit URL; needs no stored profile
@@ -5495,7 +5766,7 @@ async function main(argv) {
     process.stderr.write(`\r[${e.phase}] ${e.message}${pct}          `);
     if (e.phase === "done") process.stderr.write("\n");
   };
-  const dirArg = (i) => (0, import_node_path7.resolve)(cmd[i] ?? ".");
+  const dirArg = (i) => (0, import_node_path8.resolve)(cmd[i] ?? ".");
   const resolutionInput = async (dir) => {
     let association;
     if (dir && await isGitRepo(dir)) association = (await readAssociation(dir))?.endpoint;
@@ -5524,6 +5795,11 @@ async function main(argv) {
     const token = str2(flags["token"]);
     return { endpoint, p: createPublisher({ endpoint, endpointSource: source, ...token ? { token } : {}, clientName: "git-publisher-cli", clientVersion: CLIENT_VERSION }) };
   };
+  if (flags["version"] === true) {
+    process.stdout.write(`${packageVersion()}
+`);
+    return 0;
+  }
   switch (flags["help"] === true ? "help" : cmd[0]) {
     case void 0:
     case "help":
@@ -5669,19 +5945,30 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
         await p.getRepository(repoId);
       }
       await p.associate(dir, repoId);
+      const workspace = await p.adoptWorkspace(dir).catch(() => null);
       out({
         ok: true,
         repoId,
         created,
         endpoint,
         dir,
-        onboarding: onboarding ? { commit: onboarding.commit, committed: onboarding.committed.length, excluded: onboarding.excluded } : null
+        onboarding: onboarding ? { commit: onboarding.commit, committed: onboarding.committed.length, excluded: onboarding.excluded } : null,
+        workspace: workspace === null ? null : { branch: workspace.branch, baseOid: workspace.baseOid, baseGeneration: workspace.baseGeneration }
       });
       return 0;
     }
     case "publish": {
       let finishPublish2 = function(o) {
-        out({ state: o.state, publicationId: o.publicationId, repoId: o.repoId, generation: o.resultGeneration, refs: o.refs, rejection: o.rejection, resumed: o.resumed });
+        out({
+          state: o.state,
+          publicationId: o.publicationId,
+          repoId: o.repoId,
+          generation: o.resultGeneration,
+          refs: o.refs,
+          rejection: o.rejection,
+          resumed: o.resumed,
+          ...o.next === null ? {} : { next: o.next }
+        });
         return o.state === "accepted" ? 0 : o.state === "rejected" ? 2 : 3;
       };
       var finishPublish = finishPublish2;
@@ -5717,7 +6004,13 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       const resolved = await p.resumePublications(dir, { onProgress: progress });
       out({
         pending: pending.map((x) => x.publicationId),
-        resolved: resolved.map((o) => ({ publicationId: o.publicationId, state: o.state, generation: o.resultGeneration, rejection: o.rejection }))
+        resolved: resolved.map((o) => ({
+          publicationId: o.publicationId,
+          state: o.state,
+          generation: o.resultGeneration,
+          rejection: o.rejection,
+          ...o.next === null ? {} : { next: o.next }
+        }))
       });
       return resolved.every((o) => o.state === "accepted") ? 0 : resolved.some((o) => o.state === "rejected") ? 2 : 3;
     }
@@ -5745,12 +6038,40 @@ Waiting (it expires in ${Math.round(expiresInSeconds / 60)} minutes)...
       out(s);
       return s.state === "conflict" ? 2 : 0;
     }
+    /**
+     * The creator's one verb: record the folder's changes, bring in what the service has, publish.
+     * `--apply` is what this was before it recorded and published, and is still accepted, so a
+     * `sync --apply` written down anywhere does the whole round trip rather than failing.
+     */
     case "sync": {
       const dir = dirArg(1);
       const { p } = await client(dir);
-      const r = await p.sync({ directory: dir, apply: flags["apply"] === true, ...optStr(flags, "message") }, { onProgress: progress });
-      out({ ok: true, before: r.before.state, applied: r.applied, after: r.after, base: { oid: r.mapping.baseOid, generation: r.mapping.baseGeneration }, hint: r.before.hint });
-      return r.after === "conflict" ? 2 : 0;
+      const r = await p.syncChanges({ directory: dir, markConflicts: flags["mark-conflicts"] === true, ...optStr(flags, "message") }, { onProgress: progress });
+      const o = r.published;
+      out({
+        ok: r.state === "published" || r.state === "up_to_date",
+        state: r.state,
+        recorded: r.recorded,
+        merged: r.reconciled.applied,
+        conflicts: r.reconciled.before.conflicts,
+        marked: r.marked,
+        publication: o === null ? null : {
+          state: o.state,
+          publicationId: o.publicationId,
+          generation: o.resultGeneration,
+          refs: o.refs,
+          rejection: o.rejection,
+          ...o.next === null ? {} : { next: o.next }
+        },
+        hint: syncHint(r.state, r.reconciled.before.conflicts, r.marked)
+      });
+      return r.state === "published" || r.state === "up_to_date" ? 0 : r.state === "unknown" ? 3 : 2;
+    }
+    case "skills": {
+      if (cmd[1] !== "install") throw new PublisherError("INVALID_REQUEST", `unknown skills command: ${cmd[1] ?? "(none)"}; expected install`);
+      const r = await installSkills({ log });
+      out(r);
+      return 0;
     }
     case "merge-check": {
       const dir = dirArg(1);
@@ -5796,6 +6117,20 @@ function demand(r, input) {
       throw new PublisherError("LOCAL_STATE", `not connected to a publishing service yet.${run}`, { details });
   }
 }
+function syncHint(state, conflicts, marked) {
+  switch (state) {
+    case "published":
+      return "Your changes are saved and published.";
+    case "up_to_date":
+      return "Nothing new to publish: the service already has this version.";
+    case "conflict":
+      return marked ? `Both versions are now in ${conflicts.join(", ")}, between <<<<<<< and >>>>>>> lines. Edit each to what should be kept, remove those lines, then run publisher sync.` : `Your changes and the published version both changed ${conflicts.join(", ")}. Nothing was published and nothing was lost; decide which version to keep.`;
+    case "rejected":
+      return "The service refused the publication; see publication.rejection.";
+    default:
+      return "The publication was sent but its outcome is not known yet; run publisher status.";
+  }
+}
 function formatHuman(v) {
   return JSON.stringify(v, null, 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnovate/shadow-publisher",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "publisher: publish an app's Git history to the serverless Git backend",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,8 @@
     "publisher": "./dist/publisher.cjs"
   },
   "files": [
-    "dist/publisher.cjs"
+    "dist/publisher.cjs",
+    "dist/claude"
   ],
   "publishConfig": {
     "access": "public"
@@ -19,8 +20,8 @@
   "scripts": {
     "build": "tsc -b tsconfig.json && pnpm run bundle",
     "test": "vitest run --project unit --root ../.. packages/cli/",
-    "bundle": "esbuild src/main.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/publisher.cjs --banner:js=\"#!/usr/bin/env node\" --log-level=warning",
-    "plugin:build": "mkdir -p ../../integrations/claude/plugin/skills/publish-app/bin && cp dist/publisher.cjs ../../integrations/claude/plugin/skills/publish-app/bin/publisher.cjs",
+    "bundle": "esbuild src/main.ts --bundle --platform=node --target=node22 --format=cjs --outfile=dist/publisher.cjs --banner:js=\"#!/usr/bin/env node\" --log-level=warning && pnpm run skills",
+    "skills": "rm -rf dist/claude && mkdir -p dist/claude && cp -R ../../integrations/claude/.claude-plugin ../../integrations/claude/plugin dist/claude/",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {