sync

Files (2)

• SKILL.md
• reference.md

SKILL.md (first lines)

# Sync Kronael toolkit

**Sync** is this repo ↔ `~/.claude/` on this host, and nothing else: work done
in `~/.claude/` since the last sync merges into the repo, then `~/.claude/`
gets the repo's bundle fresh plus the owner's keep-list, so a file the source
dropped cannot linger. The old bundle moves to a run dir under `/tmp`; nothing
is deleted. A first setup is a sync into an empty `~/.claude/`. NOT sync —
NEVER run either as part of it: **push** (repo → `origin`, `git push` under
WISDOM § Git) and **merge origin** (`origin` → the repo's git line, `merge`).

## Terms

- **source** (`SRC`) — the repo working tree: CWD if it holds the assets
  below, else `CLAUDE_PLUGIN_ROOT`. Merge-back writes here, so a live edit
  survives only in the owner's clone — NEVER a plugin or marketplace snapshot.
- **live** — `~/.claude/`. **bundle** — the live paths sync owns and replaces:
  `skills/ agents/ hooks/ output-styles/ commands/ CLAUDE.md RECLAUDE.md
  kronael-install-manifest.json`. NOTHING else in `~/.claude/` moves:
  credentials, `settings*.json`, `LOCAL.md`, `CLAUDE.local.md`, `projects/`,
  `plugins/`, history and hook `state/` stay put.
- **manifest** — `kronael-install-manifest.json`: `release` (`version`,
  `gitCommit`, `gitDescribe`, `installedAt`) and `files`
  (`".claude/<path>": {source, source_sha256}`), the sha of each file as the
  last sync wrote it (`CLAUDE.md`: the wisdom body).
- **keep-list** — `~/.claude/.keep`, the installed-only paths a sync carries
  over (`reference.md` § Keep-list); a symlink directly in a bundle dir is kept
  without a line. It lives outside the bundle and NEVER enters the repo.
- **run dir** (`RUN`) — `${TMPDIR:-/tmp}/kronael-sync-<UTC stamp>/`: scratch,
  backups for steps 5-6, and `old/`, the moved-aside bundle.

## Order of operations

`/tmp` is cleared on reboot, so the run dir MUST never hold the only copy of
work the owner wants. ALWAYS merge live edits into the repo (step 2) BEFORE
the swap (step 4) — NEVER swap first and merge from `/tmp` afterwards. What
ends only in the run dir is what the owner chose not to carry: unkept
installed-only paths and declined edits. Stopping anywhere before step 4
leaves `~/.claude/` untouched.

## Plan & consent

A **first sync** = neither `~/.claude/CLAUDE.md` nor `~/.claude/skills/`
exists. Before any write, explain sync in 2-3 lines and ask which groups to
run (Claude: AskUserQuestion multiSelect; Codex: numbered options): **Bundle**
(default on — nothing else works without it), **Settings** (step 5),
**External tools** (step 7 core), **CLI tools** rig/udfix/speclint + CDPATH, **qemubox**
(needs Docker), **Heavy** security-audit + video, **ripwire**, and **Server memory**
(`reference.md` § Server memory; NEVER offer when `CLAUDE_SANDBOX` is set).
Run ONLY the opted-in groups.

Every later sync skips the questionnaire but ALWAYS still runs step 5's
always-apply set and steps 7-8 —
NEVER skip tools or qemubox silently; a stale binary or an un-offered dep is
the failure. Settings still confirm before applying.

## Steps

0. **Preflight.** Verify at `SRC`: `skills/ agents/ hooks/ hooks/lib/
   output-styles/ commands/ codex-hooks.json settings-recommended.json
   RECLAUDE.md codex/AGENTS.md` — missing means the wrong directory: stop and
   ask. No `kronael@*` in `~/.claude/plugins/installed_plugins.json` → note
   `/kronael:sync` won't resolve; the user says "sync" in this repo. A leftover
   `~/.claude/.kronael-sync-new` or `.kronael-sync-old` is a killed swap or a
   failed rollback: STOP, show both, ask — NEVER delete or reuse either; `-new`
   holds new copies not swapped in, `-old` old copies swapped out (those live
   paths are new). Export `SRC` and `RUN`, `mkdir "$RUN"`, write `reference.md`
   § Keep-list's `keep.py` there. Read the manifest `release` and report
   installed → source (commit, version, the `## [vX.Y.Z]` CHANGELOG sections
   between); no manifest means "first tracked sync".
   Completion criterion: assets verified, `RUN` printed, release delta
   written down, no leftover swap dir.

1. **Classify.** Run `reference.md` § Classify (read-only). Every live bundle
   file lands in one class, compared by sha256 — live `I`, source `S`, manifest
   `M`: `same` (I = S), `stale` (I = M, or I is a committed source version: an
   older install), `edited` (S = M: only live changed), `both` (all three
   differ), `merged` (a `both` already in the repo), `no-base` (no `M`),
   `kept`, `shadow`, `retired` (a dropped name, unedited), `only-live` (no
   source counterpart, not kept), `junk` (caches, a session's `.claude/`).
   Exit 1 = a `BADKEEP`, `SYMLINK` or `UNRESOLVED` line; step 3 settles each.
   Completion criterion: the class counts and every decision line printed.

2. **Merge live edits into the repo.** `SRC` is the owner's clone only if
   `git -C "$SRC" rev-parse --show-toplevel` = `realpath "$SRC"` and it is
   not under `~/.claude/plugins/` or `~/.codex/`. A snapshot and any
   `edited`/`both`/`no-base` line → STOP: list them, rerun from the clone
   (`LOCAL.md` names it); NEVER swap them away.
   - `edited` → copy the live file over the repo file.
   - `both` → three-way merge per `reference.md` § Merge; a clean result goes
     into the repo; conflicts → show the hunks, ask: hand-merge, take repo, or
     take live. A base whose sha ≠ `M` is no base.
   - `no-base` → show `diff -u <repo> <live>`, ask: take live, move it to
     `LOCAL.md` (a first sync over a personal `CLAUDE.md`), or keep repo.
   - `CLAUDE.md` is the body of `skills/global/SKILL.md` — keep its
     frontmatter. NEVER merge the Codex block (`codex/AGENTS.md` markers) in.
   - The repo is public: ALWAYS read every incoming hunk for local paths, host
     or org names and secrets, and move those to `~/.claude/LOCAL.md`
     (auto-injected by `local.py`) or drop them — NEVER into the repo.
   - A declined edit ends in `RUN/old` with the old bundle: name it.
   - Then `make skills-frontmatter` (`-fix` if it reports YAML).
   Completion criterion: each such path has an outcome (merged, LOCAL.md,
   declined); `git -C "$SRC" diff --stat` shows the merged files; no
   `^<<<<<<<` line in them; the lint exits 0.

3. **Decide installed-only paths.** For each `only-live` entry show what it is
   and ask: **keep** (append it to the keep-list), **repo** (generic content
   only, on the owner's explicit yes — copy it into `SRC`), or **leave** (the
   default; it ends in `RUN/old`). NEVER put an installed-only path in the repo
   without that yes — it may be an org or private skill — and NEVER drop one
   unlisted. Each `shadow` or `BADKEEP`: the owner fixes or deletes the line,
   or `mv`s a lineless kept symlink into `RUN`. Each `SYMLINK`: the owner makes
   a root a real dir, keeps a nested one by a line, or `mv`s it into `RUN`.
   Each `UNRESOLVED` hook path MUST be kept or unwired first: a missing hook
   script makes `python3` exit 2, which Claude Code treats as blocking — every
   prompt and tool call in every session fails.
   Completion criterion: rerun § Classify exits 0 with no `shadow` line, and
   every `only-live` line has an answer or the stated default.

4. **Swap.** Re-run § Classify first: exit 1 → back to step 3; an `edited`,

From kronael/tools, Unlicense.

More from kronael/tools