@hiveku-apps/sync 0.3.6 → 0.5.0

package/README.md

@@ -6,10 +6,13 @@ Local sync CLI for a Hiveku account. Pairs with the Hiveku MCP server at
 1. **`hiveku-sync init <slug>`** — scaffold a per-account folder with `.env`,
    `.mcp.json`, `CLAUDE.md`, and the empty `memory/ rules/ skills/` tree.
 2. **`hiveku-sync pull`** — fetch the account's memory/rules/skills via the
-   `memory_list` MCP tool and write each entry as a Markdown file with
-   YAML frontmatter (name, type, domain, department, version, updated_at).
+   `memory_list` MCP tool and write each entry as a Markdown file, filed under
+   the agent that owns it (see "Filed by owner" below), with YAML frontmatter
+   (id, name, type, domain, owner, version, updated_at).
    It also writes the account memory (see "Account memory" below) to
-   `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only.
+   `hiveku-data/account/ACCOUNT_MEMORY.md`, read-only, and brings the folder
+   layout and memory rules in `CLAUDE.md` up to date (see "CLAUDE.md stays
+   current" below).
 
 The goal: open one folder per Hiveku tenant in VS Code with Claude Code,
 and the local `.md` files become the source-of-truth Claude reads. Tools
@@ -105,7 +108,20 @@ This writes, merge-safely (only Hiveku-managed regions are touched):
   `OLYMPUS_API_KEY` env var. Also wires `playwright` for visual checks.
 - **`.agents/skills/<name>/SKILL.md`** — the account's pulled `skills/` and
   `commands/` mirrored as repo-scoped Codex skills (Codex prompts are global-only
-  and deprecated).
+  and deprecated), named for the agent that owns each one:
+  `hiveku-<agent>-<slug>` for a skill, `hiveku-<agent>-cmd-<slug>` for a
+  shortcut (`shared` for one every agent shares), in hyphen case and at most 64
+  characters. A mirrored skill whose source is gone, or that an older release
+  mirrored under another name (`hiveku-skill-<slug>`, `hiveku-cmd-<slug>`), is
+  removed, unless its folder holds anything besides our generated `SKILL.md`.
+  Your own skills (no hiveku-sync stamp) are never touched. Entries under a
+  `not-followed/` folder are not mirrored: no agent reads them.
+
+`AGENTS.md` also carries a short **rules digest per agent**: who follows what,
+then one line per agent with its rule count and first rule names, from the rules
+the last `pull` wrote under `rules/<agent>/` (never those in
+`rules/<agent>/not-followed/`). Run `hiveku-sync codex` after `pull` to refresh it
+(`pull` reminds you when the folder has a Codex lane).
 
 Pass `--trust` to pre-trust the folder in `~/.codex/config.toml` (so Codex loads
 the repo config without its first-run trust prompt).
@@ -177,10 +193,32 @@ cd projects/<slug>
 hiveku-sync pull-env                    # secrets → .env.local (git-ignored)
 # ...edit files, run the dev server...
 hiveku-sync status                      # diff local vs the deploy source
-hiveku-sync push                        # save changes to the deploy source
+hiveku-sync push -m "Updated the pricing section on the Home page"
+                                        # save changes, then save them as one version
 hiveku-sync push --deploy development --wait   # ...then deploy and wait
 ```
 
+`pull-project` pages through the site (`project_vcs_checkout` with `limit`,
+then `cursor`), so a site of any size comes down, including the ones over
+150 MB that cannot be sent in one answer. `--branch <name>` pulls that
+branch's working tree instead of Your site; `.hiveku/projects.json` records
+the branch, the version the pull came from (`head_commit_id`) and, on a
+branch, its `working_tree_etag`. Later `push`, `status`, `commit`,
+`versions` and `rollback` in that folder act on the same branch unless you
+pass `--branch` (`--branch main` for Your site).
+
+Each pull also records the files it wrote (`.hiveku/pulled/<slug>.json`). The
+next pull moves the ones its tree no longer has (another branch's files, files
+deleted on Hiveku) out of the project folder into
+`.hiveku/set-aside/<slug>/<time>/`, so a push can never send them back; files
+you created yourself are listed, never moved. The run hints go to the project
+folder's `.hiveku/RUN.md`, which push never sends.
+
+On a branch, `push` compares the branch's `working_tree_etag` with the one
+recorded at pull time. If someone saved on the branch since, it lists the files
+that may hold their work and changes nothing (exit 1); pull again, or pass
+`--force` to overwrite them.
+
 **`push` writes the deploy source, lane-routed.** This is the important part.
 `deploy_site` builds from `builder_code_versions` (+ the S3/CDN asset store) —
 **not** a GitHub branch. So `push`:
@@ -195,17 +233,65 @@ hiveku-sync push --deploy development --wait   # ...then deploy and wait
 - diffs correctly: code via a single `project_files_status` call (so
   `only_remote` stays reliable — chunking it produces phantom deletions), assets
   via `assets_list` (so unchanged images aren't re-uploaded every push).
+- sends each batch again with only the files that did not land (a large batch
+  can stop at the route's time budget and name the rest in `remaining_paths`),
+  and lists every file that still did not save.
+- with `--include-deletes`, deletes only files this folder could hold: never
+  dot files (`.gitignore`, `.ai/memory.md`), build folders, or files Hiveku
+  manages (`soul.md`, `data/marketing/...`), which a pull never brings down.
 
 Flags: `--include-deletes` (remove code paths missing locally), `--no-assets` /
-`--assets-all`, `--commit "msg"` (also record a Hiveku-native `main` commit),
-`--deploy <env> [--wait]`, `--dry-run`.
+`--assets-all`, `-m "name"` (the version name; `--commit "name"` still works),
+`--no-version`, `--branch <name>`, `--force`, `--deploy <env> [--wait]`,
+`--dry-run`. Images, fonts and videos live in one asset store shared by Your
+site and every branch, so a push to a branch says so before it uploads them
+(and in `--dry-run`). `--deploy` publishes what that tier is set to publish:
+Your site, unless the tier is bound to the branch.
 
 ```bash
 hiveku-sync deploy <development|staging|production> [<slug>] [--wait]
 hiveku-sync pull-env [<slug>] [--target development|staging|production]
-hiveku-sync commit -m "msg"   # legacy GitHub-branch commit (GitHub-connected projects only)
 ```
 
+## Versions
+
+"Your site" is the project's main source: what the preview shows and what a
+deploy ships. A save is live there at once, but it is not a **version** until
+one is saved, and a version is what you can go back to.
+
+- **`push` saves one version** after every file has landed:
+  `project_vcs_commit` with no files and no deletions (source `sync_cli`),
+  which saves everything on Your site (or the branch) not yet in a version,
+  from every writer (the Hiveku AI, the editor, other tools). So the name comes
+  from `-m`, otherwise from everything `project_vcs_status` says is waiting
+  ("Added the Pricing page and edited the Home page"), or only from the pages
+  the push changed on a server that cannot say. The first version after a
+  version from before versions of Your site is named by Hiveku ("Your site up
+  to <date>"). `--no-version` skips it.
+- **Names are read by the site owner.** Describe what changed for visitors;
+  never file paths, file extensions, `fix:`-style prefixes or tool names.
+  A typed name that breaks this is refused before anything is written.
+- **Exit codes:** `0` done; `1` some files did not save, or the push was
+  refused (they are listed, and there is no version and no deploy); `2` every
+  file IS saved but the version was not (the message says why and prints the
+  exact `hiveku-sync commit` that tries again); `3` the files and the version
+  ARE saved and only the deploy failed (`hiveku-sync deploy` tries again).
+
+```bash
+hiveku-sync commit [-m "name"]          # save what is waiting as one version (sends no files)
+hiveku-sync commit --github -m "msg"    # the old GitHub push (GitHub-connected projects only)
+hiveku-sync versions [--limit 50]       # the versions, newest first, and what is waiting
+hiveku-sync rollback <version id>       # dry run: what going back would change
+```
+
+`rollback` is a dry run unless you add `--apply`, and `--apply` needs the
+`--confirm` id the dry run printed (it prints the whole command), so it only goes
+ahead if nobody changed the site since you looked. Rolling back writes a NEW
+version equal to the old one, so it can be undone, saves unsaved changes as
+their own version first, and never publishes: run `hiveku-sync deploy` after
+it when the live site should match. Images, fonts and videos in the shared
+asset store, the database, CMS entries and secrets are not part of versions.
+
 `pull-env` applies the same `_DEV` / `_PROD` / `_STAGING` suffix resolution the
 preview machine uses: for `development` it strips `_DEV` to the base key and
 skips `_PROD`/`_STAGING`; `--target production` does the inverse.
@@ -220,6 +306,11 @@ skips `_PROD`/`_STAGING`; `--target production` does the inverse.
 - **No deletes in v1** — entries removed in Olympus are *not* deleted
   from disk; they're listed under `removed_remotely_since_last_sync` in
   the manifest. Prune manually if you want.
+- **Moved, never deleted** — when an entry the last pull wrote now lands
+  somewhere else (its owner changed, or an older release wrote it flat as
+  `<type>/<name>.md`), or is no longer mirrored, the old copy is moved to
+  `.hiveku/set-aside/knowledge/<time>/`. Files a pull did not write are never
+  moved. When the listing fails, nothing is moved or reported as removed.
 
 ## How writes work
 
@@ -227,6 +318,89 @@ For **projects**, `hiveku-sync push` / `deploy` write straight back to Hiveku
 (see "Coder projects" above). For **memory/rules/skills**, `pull` is read-only —
 persist changes with the `memory_create` / `memory_update` / `memory_delete` MCP
 tools through Claude, then `hiveku-sync pull` to refresh the local copies.
+`memory_update` replaces the whole entry: send
+`memory_update({ memory_id, content, reason, expected_version })` after checking
+`memory_log_list({ memory_id, since })` for changes made since you read it.
+`CLAUDE.md` says so in the part `pull` keeps current, also in folders an older
+release made (see "CLAUDE.md stays current" below), and `AGENTS.md` in the
+region `hiveku-sync codex` rewrites.
+
+## CLAUDE.md stays current
+
+`init` writes `CLAUDE.md` once, and the rest of the file is yours from then on,
+except its "Folder layout" and "Memory writes" sections. They sit between
+`<!-- hiveku:memory:begin -->` and `<!-- hiveku:memory:end -->`, and `pull` (and
+`codex`) bring them up to date, so a folder an older release made stops teaching
+the old layout and the old `memory_update` call:
+
+- the markers are there: the text between them is replaced;
+- no markers, and the two sections are exactly what an earlier release wrote
+  (0.1.0 to 0.4.0): they are replaced by the marked part, and the rest of the
+  file is kept byte for byte;
+- you edited those sections: the marked part is added at the end, your text is
+  left as it is, and the marked part says it wins where the two disagree.
+
+A `CLAUDE.md` that is read-only, a link to another file, or whose markers are not
+there once each and in order is left alone (`pull` says so). `pull` never creates
+a missing one.
+
+## Filed by owner
+
+`pull` lists every account-level entry with one `memory_list` call and files each
+one under the agent that owns it, the way the Hiveku Memory page does:
+
+```
+rules/sales/<name>.md        a rule Sales owns
+rules/seo/<name>.md          a rule the SEO topic owns (each Marketing topic is its own owner)
+rules/marketing/<name>.md    a rule the Marketing parent owns
+rules/shared/<name>.md       a rule shared with every agent
+skills/<agent>/, memory/<agent>/, commands/<agent>/, agents/<agent>/, identity/<agent>/
+```
+
+The owner is the `owner` field `memory_list` returns (the builder's one owner
+rule). A builder that does not return it yet gets the same rule from
+`src/memory-owner.mjs`: for a rule, skill, shortcut or specialist, the
+`department` column when it is set and is not `marketing`; a `marketing` or empty
+column with a Marketing-family marker (`<!-- department: seo -->`) belongs to
+that topic (the seeded starter rows); a `marketing` column without one stays with
+the Marketing parent; an empty column falls to the marker, then the front matter,
+then the shape of the name, else the entry is shared with every agent.
+
+Who follows what: an agent follows the files in its own folder and `shared/`;
+every Marketing topic also follows `marketing/`; the website agent (`coder`) also
+follows `marketing/` and the website topics; calls follow only the receptionist's
+own call rules.
+
+An entry filed under an owner that no agent reads goes one folder down, in
+`<type>/<owner>/not-followed/`: the Memory page does not show it, and its front
+matter says `followed_by: "no agent"`. That is a rule, skill or note filed for the
+chief of staff outside her own `_account:*` rows (she never reads those), an owner
+that is no agent (`mini`, `graphic_design`), or a note a department owns under a
+name its agent never reads (Sales reads its `sales` notes, not `pipeline-notes`).
+The builder's `placement` says which (hidden, for a reason other than internal
+state); an older builder gets the same rule from `src/memory-owner.mjs`. The Codex
+rules digest and skill mirror leave these out.
+
+The chief of staff's own rows (`_account:*`) and Voice and pronunciation are
+placed where the Memory page shows them, **read-only** (owners and admins change
+them on the Memory page; the front matter carries the `edit_url`):
+
+```
+memory/orchestrator/how-it-works.md   How it works (_account:soul)
+memory/orchestrator/background.md     Background (_account:claude)
+rules/orchestrator/, skills/orchestrator/, memory/orchestrator/<topic>.md
+memory/orchestrator/moved/<topic>.md  topics now kept in About your business
+hiveku-data/account/voice/<name>.md   Voice and pronunciation
+```
+
+A file under `moved/` is her old copy: it opens with a line naming the About your
+business heading the topic moved to and saying that the current text is in
+`hiveku-data/account/ACCOUNT_MEMORY.md`.
+
+Internal rows the page never shows (`_workspace:*`, `_digest:*`, a row that
+holds only the agents' security preamble, an old `_account:*` shape) are not
+written. A name that a tool would read as its own instructions (`claude`,
+`agents`) or that Windows keeps for a device gets `-entry` added.
 
 ## Account memory
 
@@ -245,7 +419,7 @@ suggested it and when. The two account-memory rows (`account` and
 `account-suggestions`) are never written under `memory/`, even when an older
 server still lists them.
 
-Nothing uploads this file: `push`, `commit` and `status` leave any
+Nothing uploads this file: `push`, `commit --github` and `status` leave any
 `hiveku-data/account/` folder out, and the next `pull` replaces it. To add a
 fact, suggest it with the `account_memory_append` tool; an owner keeps or
 removes it on the dashboard.

package/bin/hiveku-sync.mjs

@@ -18,6 +18,9 @@ import {
   runProjectPush,
 } from '../src/projects.mjs';
 import { runPush, runDeploy, runPullEnv } from '../src/push.mjs';
+import { runRollback, runVersionCommit, runVersions } from '../src/versions.mjs';
+import { ownerOrder } from '../src/memory-owner.mjs';
+import { relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 export function parseFlags(argv) {
@@ -34,6 +37,9 @@ export function parseFlags(argv) {
     'branch',
     'profile',
     'parent',
+    'confirm',
+    'fingerprint',
+    'limit',
   ]);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -75,8 +81,12 @@ Memory/rules/skills:
                                     + .codex/config.toml + skills); --trust
                                     pre-trusts the folder in ~/.codex/config.toml.
   pull [--profile=<name>]           Pull memory/rules/skills via MCP into the
-                                    current account folder. Reads OLYMPUS_API_KEY
-                                    and OLYMPUS_BASE_URL from ./.env.
+                                    current account folder, filed by the agent
+                                    that owns each one (<type>/<agent>/, and
+                                    <type>/shared/ for every agent). Brings the
+                                    folder layout and memory rules in CLAUDE.md
+                                    up to date. Reads OLYMPUS_API_KEY and
+                                    OLYMPUS_BASE_URL from ./.env.
   codex [<folder>] [--trust]        Retrofit an existing account folder with the
                                     Codex lane (AGENTS.md + .codex/config.toml +
                                     mirror the account's skills/commands to
@@ -89,27 +99,59 @@ Memory/rules/skills:
 
 Coder projects:
   projects                          List the account's coder projects.
-  pull-project <slug-or-id>         Pull a project's source into ./projects/<slug>/.
-                  [--branch=<name>] Records the project mapping in .hiveku/projects.json.
+  pull-project <slug-or-id>         Pull Your site's files (or, with --branch, that
+                  [--branch=<name>]   branch's working tree) into ./projects/<slug>/,
+                                      page by page (any size). Records the project,
+                                      branch and version in .hiveku/projects.json.
+                                      Files an earlier pull wrote that are not in
+                                      this one move to .hiveku/set-aside/<slug>/.
   status [<slug>] [--json]          Diff local ./projects/<slug>/ vs the deploy source
-                                    (builder_code_versions). cd in to omit <slug>.
+         [--branch=<name>]            (builder_code_versions), or the pulled branch.
+                                      cd in to omit <slug>.
 
 Ship a project (the agent-native deploy loop):
   push [<slug>]                     Save local changes to the DEPLOY SOURCE, lane-routed:
-       [--include-deletes]            images/fonts/video under public/<subdir>/ → the
-       [--no-assets] [--assets-all]   S3/CDN asset store; everything else → batched,
-       [--commit "<msg>"]             verified bulk_save. This is what deploy reads.
-       [--deploy <env>] [--wait]      --commit also records a Hiveku 'main' commit.
-       [--dry-run] [--branch=<name>]  --deploy <env> [--wait] deploys after the push.
+       [-m "<version name>"]          images/fonts/video under public/<subdir>/ → the
+       [--no-version]                 S3/CDN asset store; everything else → batched,
+       [--include-deletes]            verified bulk_save. This is what deploy reads.
+       [--no-assets] [--assets-all]   Then saves ONE version of Your site (or of the
+       [--deploy <env>] [--wait]      branch) named by -m, or from the pages changed.
+       [--dry-run] [--branch=<name>]  Names are plain language for the site owner (no
+       [--force]                      file paths, extensions or "fix:" prefixes).
+                                      --no-version skips the version. --deploy <env>
+                                      [--wait] deploys after the push. --branch writes
+                                      to that branch (default: the branch pulled);
+                                      if someone saved on it since the pull, push
+                                      refuses unless --force.
+                                      Exit 0 done; 1 some files did not save or the
+                                      push was refused (no version, no deploy); 2
+                                      files ARE saved but the version was not (it
+                                      prints the \`commit\` that retries it); 3 files
+                                      and version ARE saved, the deploy failed.
   deploy <env> [<slug>] [--wait]    Deploy to development | staging | production and
                                     (with --wait) poll to a terminal status.
   pull-env [<slug>]                 Write project secrets → .env.local (git-ignored),
            [--target <env>]           with the same _DEV/_PROD/_STAGING resolution the
                                       preview uses. --target staging|production for the
                                       other tiers.
-  commit [<slug>] -m "<msg>"        GitHub-branch commit via project_commit (only for
-                  [--branch=<name>]   GitHub-connected projects; most sites use push).
-                  [--include-deletes]
+
+Versions (Your site = the project's main source; rollback never publishes):
+  commit [<slug>] [-m "<name>"]     Save what is on Hiveku and not yet in a version as
+         [--branch=<name>]            one version (no files are sent: push first).
+         [--dry-run]                  Without -m it is named from what changed. Exit 2
+                                      when the version could not be saved.
+  commit --github -m "<msg>"        The old GitHub push via project_commit (only for
+         [--branch=<name>]            GitHub-connected projects).
+         [--include-deletes]
+  versions [<slug>] [--branch=<b>]  The versions, newest first, and what is waiting.
+           [--limit N] [--json]
+  rollback <version id> [<slug>]    Show what going back to that version would change.
+           [--branch=<name>]          Nothing changes (a dry run). It prints the exact
+           [--apply --confirm <id>]   --apply command, with the --confirm id it saw;
+           [--fingerprint <fp>]       applying writes a NEW version equal to the old one
+           [-m "<name>"]              (so it can be undone) and is refused if the site
+                                      changed since the dry run. Publish separately
+                                      with deploy.
 
   help                              Show this message.
 
@@ -140,19 +182,56 @@ function userToolTablesLines({ userToolTables = [], userTablesWithoutApprovalMod
   return lines;
 }
 
-function commitMessageFrom(flags) {
-  // --commit "msg" | --commit=msg | -m "msg" | --message "msg". A bare --commit
-  // (boolean true) means "commit with no message" → fall back to the default.
+/**
+ * What refreshing CLAUDE.md's kept-current part (folder layout and memory
+ * rules, claude-md.mjs) did, as lines to print. Nothing when it was already
+ * current or there is no CLAUDE.md.
+ */
+export function claudeMdLines(result) {
+  switch (result?.status) {
+    case 'updated':
+    case 'replaced':
+      return ['  CLAUDE.md: brought the folder layout and memory rules up to date (the rest of the file is as it was).'];
+    case 'appended':
+      return [
+        '  CLAUDE.md: added the current folder layout and memory rules at the end, between hiveku-sync markers.',
+        '    Your file had its own version of those sections, so they were left as they are: where they disagree, the new part wins.',
+      ];
+    case 'symlink':
+      return ['  CLAUDE.md: not updated, because it is a link to another file. Its folder layout and memory rules may be out of date.'];
+    case 'read-only':
+      return ['  CLAUDE.md: not updated, because the file is read-only. Its folder layout and memory rules may be out of date.'];
+    case 'markers':
+      return [
+        '  CLAUDE.md: not updated, because the hiveku-sync markers (<!-- hiveku:memory:begin --> and <!-- hiveku:memory:end -->) are not there exactly once each, in order.',
+        '    Keep one of each, then run this again.',
+      ];
+    case 'failed':
+      return [`  CLAUDE.md: could not update the folder layout and memory rules: ${result.message}`];
+    default:
+      return [];
+  }
+}
+
+export function commitMessageFrom(flags) {
+  // --commit "msg" | --commit=msg | -m "msg" | --message "msg": the version
+  // name. A bare --commit (boolean true, from before versions were the
+  // default) names nothing: the version is then named from what changed.
   const c = typeof flags['commit'] === 'string' ? flags['commit'] : undefined;
   const m = typeof flags['m'] === 'string' ? flags['m'] : undefined;
   const msg = typeof flags['message'] === 'string' ? flags['message'] : undefined;
   if (c) return c;
   if (m) return m;
   if (msg) return msg;
-  if (flags['commit'] === true) return 'hiveku-sync: push';
   return undefined;
 }
 
+/** A command's exit code, from the result object it returned (0 when it says nothing). */
+function setExitCode(result) {
+  const code = result && typeof result.exit_code === 'number' ? result.exit_code : 0;
+  if (code) process.exitCode = code;
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   const { positional, flags } = parseFlags(rest);
@@ -203,9 +282,13 @@ async function main() {
           ? `  MCP auth: inlined OLYMPUS_API_KEY from .env.`
           : `  MCP auth: reads the OLYMPUS_API_KEY env var (no key found in .env to inline) — set it, or paste it into .env and re-run.`,
       );
-      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/command entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/.`);
+      console.log(`  skills: mirrored ${result.skillsMirrored} account skill/shortcut entr${result.skillsMirrored === 1 ? 'y' : 'ies'} into .agents/skills/ as hiveku-<agent>-<name>.`);
+      if (result.skillsRemoved > 0) {
+        console.log(`  skills: removed ${result.skillsRemoved} mirrored skill${result.skillsRemoved === 1 ? '' : 's'} with no source left (or an older name).`);
+      }
       if (result.trust === 'added') console.log(`  trust: pre-trusted this folder in ~/.codex/config.toml.`);
       else if (result.trust === 'already') console.log(`  trust: folder already trusted.`);
+      for (const line of claudeMdLines(result.claudeMd)) console.log(line);
       console.log(`  verify: cd there, run \`codex mcp list\` (the hiveku row), then \`get_account_info\`.`);
       break;
     }
@@ -215,6 +298,23 @@ async function main() {
       for (const [type, count] of Object.entries(summary.by_type)) {
         console.log(`  ${type}: ${count}`);
       }
+      const owners = Object.entries(summary.by_owner).sort(([a], [b]) => ownerOrder(a) - ownerOrder(b) || (a < b ? -1 : 1));
+      if (owners.length > 0) {
+        console.log(`  filed by agent (<type>/<agent>/): ${owners.map(([owner, n]) => `${owner} ${n}`).join(', ')}`);
+      }
+      if (summary.not_followed > 0) {
+        const n = summary.not_followed;
+        console.log(
+          `  not followed: ${n} entr${n === 1 ? 'y' : 'ies'} that no agent reads, in <type>/<agent>/not-followed/ (the Memory page does not show ${n === 1 ? 'it' : 'them'}).`,
+        );
+      }
+      if (summary.set_aside.length > 0) {
+        const n = summary.set_aside.length;
+        console.log(
+          `  moved ${n} older cop${n === 1 ? 'y' : 'ies'} an earlier pull wrote out of the way (now filed by agent, or no longer mirrored): ` +
+            `${relative(process.cwd(), summary.set_aside_dir) || summary.set_aside_dir}/`,
+        );
+      }
       if (summary.account_memory) {
         const am = summary.account_memory;
         console.log(
@@ -227,6 +327,10 @@ async function main() {
         for (const f of summary.removed_remotely) console.log(`  ${f}`);
         console.log('They were left on disk. Delete them manually if no longer needed.');
       }
+      for (const line of claudeMdLines(summary.claude_md)) console.log(line);
+      if (summary.codex_lane) {
+        console.log('\nCodex: run `hiveku-sync codex` to refresh the rules list in AGENTS.md and the skills in .agents/skills/.');
+      }
       if (summary.errors.length > 0) {
         console.error('\nErrors:');
         for (const e of summary.errors) console.error(`  ${e.type}: ${e.message}`);
@@ -257,12 +361,13 @@ async function main() {
         slug: positional[0],
         profile: flags['profile'],
         json: !!flags['json'],
+        branch: flags['branch'],
       });
       break;
     }
     case 'push': {
       const deployEnv = typeof flags['deploy'] === 'string' ? flags['deploy'] : undefined;
-      await runPush({
+      const result = await runPush({
         slug: positional[0],
         profile: flags['profile'],
         commit: commitMessageFrom(flags),
@@ -273,7 +378,10 @@ async function main() {
         assetsAll: !!flags['assets-all'],
         dryRun: !!flags['dry-run'],
         branch: flags['branch'],
+        noVersion: !!flags['no-version'],
+        force: !!flags['force'],
       });
+      setExitCode(result);
       break;
     }
     case 'deploy': {
@@ -301,21 +409,63 @@ async function main() {
       break;
     }
     case 'commit': {
-      // The legacy GitHub-branch commit path (project_commit). Requires a repo.
-      const message = commitMessageFrom(flags);
-      if (!message || message === 'hiveku-sync: push') {
-        console.error('Error: commit requires -m "<commit message>"\n');
-        console.error(HELP);
-        process.exit(1);
+      if (flags['github']) {
+        // The old GitHub-branch path (project_commit). Requires a connected repo.
+        const message = commitMessageFrom(flags);
+        if (!message) {
+          console.error('Error: commit --github requires -m "<message>"\n');
+          console.error(HELP);
+          process.exit(1);
+        }
+        await runProjectPush({
+          slug: positional[0],
+          message,
+          branch: flags['branch'],
+          profile: flags['profile'],
+          includeDeletes: !!flags['include-deletes'],
+          dryRun: !!flags['dry-run'],
+        });
+        break;
       }
-      await runProjectPush({
+      // Default: save what is on Hiveku as one version (no files sent).
+      const result = await runVersionCommit({
         slug: positional[0],
-        message,
+        name: commitMessageFrom(flags),
         branch: flags['branch'],
         profile: flags['profile'],
-        includeDeletes: !!flags['include-deletes'],
         dryRun: !!flags['dry-run'],
       });
+      setExitCode(result);
+      break;
+    }
+    case 'versions': {
+      const result = await runVersions({
+        slug: positional[0],
+        branch: flags['branch'],
+        limit: typeof flags['limit'] === 'string' ? flags['limit'] : undefined,
+        json: !!flags['json'],
+        profile: flags['profile'],
+      });
+      setExitCode(result);
+      break;
+    }
+    case 'rollback': {
+      if (!positional[0]) {
+        console.error('Error: rollback requires a version id (see `hiveku-sync versions`).\n');
+        console.error(HELP);
+        process.exit(1);
+      }
+      const result = await runRollback({
+        versionId: positional[0],
+        slug: positional[1],
+        branch: flags['branch'],
+        apply: !!flags['apply'],
+        head: typeof flags['confirm'] === 'string' ? flags['confirm'] : undefined,
+        fingerprint: typeof flags['fingerprint'] === 'string' ? flags['fingerprint'] : undefined,
+        name: commitMessageFrom(flags),
+        profile: flags['profile'],
+      });
+      setExitCode(result);
       break;
     }
     case 'help':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiveku-apps/sync",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "Sync a Hiveku account's memory/rules/skills + coder projects into a local folder, and ship projects (push/deploy/pull-env) from the terminal. Pairs with the Hiveku MCP at core.hiveku.com/mcp so Claude Code can drive Hiveku tools per-folder.",
   "type": "module",
   "license": "MIT",