feat(setup): make setup sync refresh-only with --install-missing opt-in

.codex/skills/hack-cli/SKILL.md

@@ -14,7 +14,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -182,7 +182,7 @@ Use `hack` as the primary interface for local-first development.
 ## Agent integration maintenance
 
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

.cursor/rules/hack.mdc

@@ -9,7 +9,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -77,7 +77,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 ## Agent integration maintenance
 
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

docs/cli.md

@@ -131,7 +131,9 @@ the Hack CLI version that generated them. Plain `hack agent prime` prints curren
 an integration scan. Use `hack agent prime --check` for an explicit project/global inventory or a
 targeted `hack setup ... --check` when diagnosing drift. Missing optional integrations do not
 require installation. Repair only affected targets within the authorized scope; use
-`hack setup sync --all-scopes` for an explicitly requested full refresh. Read updated guidance after
+`hack setup sync --all-scopes` for an explicitly requested full refresh. Sync refreshes only installed
+Hack-owned integrations; add `--install-missing` to create missing ones (see
+[integration setup](integrations.md#refresh-only-hack-setup-sync)). Read updated guidance after
 repair; restart only if the client cannot reload changed hooks or skills.
 Ordinary commands, `hack update`, and `hack doctor --fix` never render, repair, remove, or otherwise
 mutate integration files. CLI upgrades do not trigger integration updates.

docs/integrations.md

@@ -12,9 +12,10 @@ What remains:
   export commands
 
 `hack setup sync` keeps interactive output compact: it summarizes each scope and only expands the
-path and reason for stale, missing, or failed artifacts. Exit status remains the automation contract,
-and the individual `hack setup cursor|claude|codex|agents|mcp --check` commands remain available when
-you need per-artifact detail.
+path and reason for preserved or failed artifacts (and, with `--check`, the ones sync would change).
+Exit status remains the automation contract, `--json` lists every target, and the individual
+`hack setup cursor|claude|codex|agents|mcp --check` commands remain available when you need
+per-client detail.
 
 What does not ship: Hack Tickets, built-in GitHub or Linear integrations, hosted
 auth/account/org/team surfaces, and the web dashboard control plane.
@@ -48,7 +49,38 @@ files Hack owns: the current render or an unedited render from an earlier releas
 unrecognized `SKILL.md` or `hack.mdc` is reported as `preserved` with a reason and left unchanged;
 move or delete it yourself to reinstall. Removal deletes only the owned `SKILL.md` and removes its
 skill directory only when nothing else is in it. Claude hook removal drops only the
-`hack agent prime` entries and keeps other commands. Preserved files do not change the exit status.
+`hack agent prime` entries and keeps other commands. Preserved files do not change the exit status
+of an install, sync, or remove.
+
+### Refresh-only `hack setup sync`
+
+`hack setup sync` refreshes only integrations that are already installed and Hack-owned. It never
+creates a missing one. Per target, in the selected scope (project by default, `--global`, or
+`--all-scopes`):
+
+| Status | Meaning |
+| --- | --- |
+| `refreshed` | An installed Hack-owned target was rewritten to the current render |
+| `unchanged` | The target already matches the current render |
+| `preserved` | The file is customized or unrecognized; it is left byte-identical and the closed reason is reported |
+| `missing` | The target is not installed; sync skipped it |
+| `installed` | Created only with `--install-missing` |
+| `removed` | A recognized retired Hack artifact was deleted (or, with `--remove`, a Hack-owned target) |
+| `error` | The target could not be read or parsed; it is left unchanged |
+
+Hack-owned means: a current or known earlier render of a standalone skill or rule file; the
+marker-delimited section of `AGENTS.md`/`CLAUDE.md`; the `hack agent prime` entries of the Claude
+settings file; and the `hack` entry of an MCP config. A doc, settings file, or MCP config without
+the Hack section counts as `missing`, so the file is not modified. Existing MCP entries are
+never replaced.
+
+Add `--install-missing` to also create missing integrations in the selected scope; customized
+files stay `preserved`. `--check` is read-only: it reports what sync would do with the same flags
+and exits non-zero when sync would refresh, install, or remove something, a file is preserved,
+or a target errors. A missing target fails `--check` only together with `--install-missing`.
+`--json` prints `{ok, data: {action, dryRun, installMissing, counts, targets}}`, where each
+target carries `scope`, `target`, `path`, `status`, and, when preserved, `reason`. Messages are
+fixed text and never include file contents.
 
 ## Standalone MCP configuration
 

docs/reference/cli.md

@@ -1801,7 +1801,7 @@ hack setup <subcommand> [options]
 | `hack setup claude` | Install Claude Code hooks for hack CLI usage |
 | `hack setup codex` | Install Codex skill for hack CLI usage |
 | `hack setup agents` | Install AGENTS.md / CLAUDE.md snippets for hack CLI usage |
-| `hack setup sync` | Refresh project/global agent guidance |
+| `hack setup sync` | Refresh installed Hack-owned agent integrations |
 | `hack setup mcp` | Install MCP configs for hack CLI usage (no-shell only) |
 
 ### Options
@@ -1924,7 +1924,7 @@ hack setup agents [options]
 
 ## `hack setup sync`
 
-Refresh project/global agent guidance
+Refresh installed Hack-owned agent integrations
 
 ### Usage
 
@@ -1939,8 +1939,10 @@ hack setup sync [options]
 | `--path, -p <dir>` | Run a project command against a repo path (overrides cwd search) |
 | `--global` | Use global (user) scope instead of project scope |
 | `--all-scopes` | Target both project and global (user) scopes |
+| `--install-missing` | Also create missing integrations in the selected scope (default: refresh only installed Hack-owned files) |
 | `--check` | Check whether integration is installed |
 | `--remove` | Remove integration files/config |
+| `--json` | Output JSON (machine-readable) |
 | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
 | `--help, -h` | Show help |
 | `--version, -v` | Show version |

examples/basic/AGENTS.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -154,7 +154,7 @@ Daemon (optional):
 
 Agent integration maintenance:
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

examples/basic/CLAUDE.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -154,7 +154,7 @@ Daemon (optional):
 
 Agent integration maintenance:
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

plugins/hack/rules/hack.mdc

@@ -14,7 +14,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -82,7 +82,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 ## Agent integration maintenance
 
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

plugins/hack/skills/hack-branches/SKILL.md

@@ -35,4 +35,4 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).

plugins/hack/skills/hack-cli/SKILL.md

@@ -16,7 +16,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -184,7 +184,7 @@ Use `hack` as the primary interface for local-first development.
 ## Agent integration maintenance
 
 - Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or mutate agent integration files.
-- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh.
+- Use the matching `hack setup` command only for the affected client and authorized project scope; add `--global` only when user-scope changes are authorized. Use `--check` for read-only inspection. Reserve `hack setup sync --all-scopes` for an explicitly requested full refresh; it refreshes only installed Hack-owned files and creates missing integrations only with `--install-missing`.
 - Standalone setup and optional native plugins are alternative integration paths. A missing optional integration does not require installation. Verify the replacement loads before explicitly removing duplicate Hack-owned entries; preserve customizations.
 - CLI upgrades do not authorize integration changes. Edit guidance at its generator source and render the affected targets; restart only if the client cannot reload the changed hooks or skills.
 

plugins/hack/skills/hack-diagnose/SKILL.md

@@ -37,7 +37,7 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).
 
 ## References
 

plugins/hack/skills/hack-env/SKILL.md

@@ -34,4 +34,4 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `5c5c3c9fffea` (version alone is not a freshness guarantee).
+- Content revision: `5108f34edd26` (version alone is not a freshness guarantee).