`@kumokodo/sync-companion` is a Node CLI that runs on your workstation (or a sidecar host) and pushes new + modified files in configured folders to Kodori through the standard `/api/v1/documents` endpoint. Same code path as direct API uploads — dedup, audit-log append, auto-classify, and DLP all run normally.
## Install
```sh pnpm install pnpm --filter @kumokodo/sync-companion build pnpm --filter @kumokodo/sync-companion exec npm link ```
## Configure
```sh kodori-sync init $EDITOR ~/.kodori/sync-companion.json ```
Required fields: `baseUrl`, `apiKey` (a `k_<prefix>_<secret>` from /api-keys with the `documents:write` scope), `watchPaths` (array of absolute folder paths to watch).
Optional: `defaultSensitivity` (forwarded as `X-Kodori-Sensitivity`), `defaultCollectionId` (forwarded as `X-Kodori-Collection-Id`), `ignoreGlobs` (defaults to `**/node_modules/**`, `**/.git/**`, `**/.DS_Store`), `minStableMs` (chokidar `awaitWriteFinish` stability threshold; default 5000 ms — tune up for slow scanners writing in chunks).
## Run
```sh kodori-sync # foreground watcher kodori-sync --once # one-shot backfill — upload everything currently present, then exit kodori-sync --config PATH # use a non-default config file ```
## Operational notes
Each upload forwards `X-Kodori-Metadata: {syncCompanion: {sourcePath, hostname, pushedAt}}` so operators can trace which sidecar pushed a particular doc on the document detail page + the audit feed. The CLI honors server-side dedup (CAS hits return `deduped: true` and don't re-store). 50 MB sync-upload cap matches the API; oversize files emit a clear skip message rather than wasting the round-trip on a known-413 path.
API key rotation: revoke the old key on /api-keys, mint a new one with documents:write, replace `apiKey` in the config, restart the sidecar. The companion logs `apiKey` lookups via the standard auth path — invalid / expired / revoked keys surface as 401 errors with reason in the response logs.
## Future hardening
The Electron tray app wrapper (auto-updater, OS notifications, queue persistence across restarts) will land when a customer asks. The CLI here is the productization baseline — the Electron version becomes a thin shell over the same `uploadFile` + `chokidar` core.