refactor: address remaining panel review items

- Fix stale _CONFIG_KEY_DISPLAY_NAMES entry (ssh -> prefer_ssh)
- Lowercase bool output in apm config get (True/False -> true/false)
- Suppress false-default transport rows in apm config / apm config get
- Success message: "set to true/false" instead of "enabled/disabled"
- FALLBACK_HINT: mention apm config set as persistent alternative

config.py
- Add _unset_config_key(key) private helper; delegate all four
  unset_* functions through it (DRY, Python Architect recommended)

commands/config.py
- Emit logger.warning() when allow-protocol-fallback is persisted in
  a CI environment ($CI set) advising APM_ALLOW_PROTOCOL_FALLBACK=1
  for invocation-scoped use instead (Supply Chain Security recommended)

install/validation.py
- Rename allow_fallback_env -> allow_fallback; _env suffix was
  misleading after the value started resolving from config too
  (Auth Expert nit)

deps/github_downloader.py
- Update __init__ docstring for protocol_pref and allow_fallback to
  accurately describe env > config > default resolution instead of
  implying env-only lookups (Auth Expert recommended)

CHANGELOG.md
- Merge second ### Added block bullets into first; restore ### Fixed
  section; one subsection per type per release per Keep a Changelog
  (Doc Writer recommended)

docs/getting-started/authentication.md
- Add forward-pointer to "apm config set prefer-ssh false" after the
  APM_GIT_PROTOCOL=https escape-hatch block; highest-intent
  conversion point for the new config surface (OSS Growth Hacker
  recommended)

Author: Aaryan-Dadu

CHANGELOG.md

@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `apm config set prefer-ssh true` / `apm config set allow-protocol-fallback true` persist transport preferences to `~/.apm/config.json` so SSH-only and corporate GHES users no longer need to re-pass `--ssh` / `--allow-protocol-fallback` (or export env vars in shell profiles) on every `apm install`. Resolution order: CLI flag > `APM_GIT_PROTOCOL` / `APM_ALLOW_PROTOCOL_FALLBACK` env var > `apm config` > built-in default. `apm config unset prefer-ssh` and `apm config unset allow-protocol-fallback` remove the persisted value. (#1243)
+- `apm pack --marketplace=FORMATS` filters which marketplace formats are built in a single run; accepts comma-separated names and sentinels `all`/`none`. (#1317)
+- `apm pack --marketplace-path FORMAT=PATH` overrides the output path for a specific marketplace format at invocation time. Env var overrides (`APM_MARKETPLACE_<FORMAT>_PATH`) are planned for v0.15. (#1317)
+- `apm pack --json` emits a stable JSON contract to stdout (`{ok, dry_run, warnings, errors, marketplace: {outputs: [{format, path, ...}]}}`); all logs move to stderr so downstream tooling can `jq` the output safely. (#1317)
+- `marketplace.outputs` in `apm.yml` now accepts a map form keyed by format name (`outputs: {claude: {}, codex: {path: ...}}`), replacing the deprecated list form; the list form still parses with a one-cycle deprecation warning. (#1317)
+- `apm marketplace init` now scaffolds the explicit map-form `outputs: {claude: {}}` so the default state is observable in the manifest. (#1317)
 
 ### Fixed
 
@@ -18,14 +23,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Non-skill integrators (agent, instruction, prompt, command, hook script-copy) silently adopt byte-identical pre-existing files so a degraded `deployed_files=[]` lockfile no longer permanently blocks installs gated by `required-packages-deployed`. (#1313)
 - `apm audit` drift check now returns skip-with-info (`passed=True`) when the install cache is cold, instead of failing the audit; bare `apm audit` surfaces the skip reason on stderr so CI pipelines that have not yet run `apm install` are not incorrectly red-marked. (#1289)
 
-### Added
-
-- `apm pack --marketplace=FORMATS` filters which marketplace formats are built in a single run; accepts comma-separated names and sentinels `all`/`none`. (#1317)
-- `apm pack --marketplace-path FORMAT=PATH` overrides the output path for a specific marketplace format at invocation time. Env var overrides (`APM_MARKETPLACE_<FORMAT>_PATH`) are planned for v0.15. (#1317)
-- `apm pack --json` emits a stable JSON contract to stdout (`{ok, dry_run, warnings, errors, marketplace: {outputs: [{format, path, ...}]}}`); all logs move to stderr so downstream tooling can `jq` the output safely. (#1317)
-- `marketplace.outputs` in `apm.yml` now accepts a map form keyed by format name (`outputs: {claude: {}, codex: {path: ...}}`), replacing the deprecated list form; the list form still parses with a one-cycle deprecation warning. (#1317)
-- `apm marketplace init` now scaffolds the explicit map-form `outputs: {claude: {}}` so the default state is observable in the manifest. (#1317)
-
 ### Changed
 
 - `--marketplace-output PATH` is now hidden from `--help` and emits a stderr deprecation warning; it auto-translates to `--marketplace-path claude=PATH`. Removal tracked in #1318. (#1317)

docs/src/content/docs/getting-started/authentication.md

@@ -449,6 +449,16 @@ apm install --https
 export APM_GIT_PROTOCOL=https
 ```
 
+To persist the HTTPS preference across all future installs without re-exporting the variable:
+
+```bash
+apm config set prefer-ssh false   # explicit: never prefer SSH for shorthand deps
+# or, if you want APM to always try HTTPS for shorthand deps:
+# export APM_GIT_PROTOCOL=https   # process-scoped; add to shell profile for persistence
+```
+
+See [apm config](../../reference/cli/config/) for the full transport-preference config surface.
+
 ## Choosing transport (SSH vs HTTPS)
 
 Authentication and transport are independent decisions:

docs/src/content/docs/reference/cli/config.md

@@ -45,7 +45,7 @@ Write `KEY` to `~/.apm/config.json`. Validates the value before writing:
 
 ### `apm config unset KEY`
 
-Remove `KEY` from `~/.apm/config.json`. No-op if the key is not set. Only `temp-dir` and `copilot-cowork-skills-dir` are unsettable; boolean keys are reset by `set`-ing them to their default.
+Remove `KEY` from `~/.apm/config.json`. No-op if the key is not set. All settable keys are unsettable: `temp-dir`, `copilot-cowork-skills-dir`, `prefer-ssh`, and `allow-protocol-fallback`. After unsetting a key the effective value falls back to the environment variable, then the built-in default.
 
 ## Configuration keys
 

docs/src/content/docs/reference/environment-variables.md

@@ -37,7 +37,7 @@ Controls how APM clones packages from Git hosts. These settings can also be pers
 
 | Variable | Purpose | Default | Notes |
 |---|---|---|---|
-| `APM_GIT_PROTOCOL` | Preferred clone protocol for shorthand (`owner/repo`) dependencies. Accepted values: `ssh`, `https`. | unset | Equivalent to `--ssh` / `--https` flag. Resolution: CLI flag → env var → `ssh` key in `~/.apm/config.json` → git `insteadOf` rules → HTTPS. |
+| `APM_GIT_PROTOCOL` | Preferred clone protocol for shorthand (`owner/repo`) dependencies. Accepted values: `ssh`, `https`. | unset | Equivalent to `--ssh` / `--https` flag. Resolution: CLI flag → env var → `prefer-ssh` key in `~/.apm/config.json` → git `insteadOf` rules → HTTPS. |
 | `APM_ALLOW_PROTOCOL_FALLBACK` | Set to `1` (or `true`/`yes`/`on`) to enable the legacy cross-protocol fallback chain. When enabled, a failed clone is retried with the opposite protocol. | unset | Equivalent to `--allow-protocol-fallback`. Resolution: CLI flag → env var → `allow-protocol-fallback` key in `~/.apm/config.json` → `false`. |
 
 ## Registry (MCP and proxy)

src/apm_cli/commands/config.py

@@ -21,7 +21,7 @@
     "temp_dir": "temp-dir",
     "copilot_cowork_skills_dir": "copilot-cowork-skills-dir",
     "allow_protocol_fallback": "allow-protocol-fallback",
-    "ssh": "ssh",
+    "prefer_ssh": "prefer-ssh",
 }
 
 
@@ -134,8 +134,14 @@ def config(ctx):
             if _temp_dir_val:
                 config_table.add_row("", "Temp Directory", _temp_dir_val)
 
-            config_table.add_row("", "Allow Protocol Fallback", str(_get_apf()))
-            config_table.add_row("", "Prefer SSH Transport", str(_get_prefer_ssh_cfg()))
+            # Only surface transport keys when they have been enabled -- the
+            # false-default rows add noise for users who never configured them.
+            _apf = _get_apf()
+            _prefer_ssh = _get_prefer_ssh_cfg()
+            if _apf:
+                config_table.add_row("", "Allow Protocol Fallback", "true")
+            if _prefer_ssh:
+                config_table.add_row("", "Prefer SSH Transport", "true")
 
             from ..core.experimental import is_enabled as _is_enabled
 
@@ -178,8 +184,8 @@ def config(ctx):
             if _temp_dir_fb:
                 click.echo(f"  Temp Directory: {_temp_dir_fb}")
 
-            click.echo(f"  allow-protocol-fallback: {_get_apf_fb()}")
-            click.echo(f"  prefer-ssh: {_get_prefer_ssh_fb()}")
+            click.echo(f"  allow-protocol-fallback: {str(_get_apf_fb()).lower()}")
+            click.echo(f"  prefer-ssh: {str(_get_prefer_ssh_fb()).lower()}")
 
             from ..core.experimental import is_enabled as _is_enabled_fb
 
@@ -252,10 +258,20 @@ def set(key, value):  # noqa: F811
 
     setter, label = config_entry
     setter(enabled)
-    if enabled:
-        logger.success(f"{label} enabled")
-    else:
-        logger.success(f"{label} disabled")
+    logger.success(f"{label} set to {'true' if enabled else 'false'}")
+
+    # Warn when persisting allow-protocol-fallback=true in a CI environment where
+    # $HOME is often shared across jobs -- the persisted value will affect all
+    # subsequent apm install runs on that host. The env var is safer for CI.
+    import os as _os
+
+    if key == "allow-protocol-fallback" and enabled and _os.environ.get("CI"):
+        logger.warning(
+            "allow-protocol-fallback is now persisted to ~/.apm/config.json. "
+            "In CI environments with a shared $HOME this will affect all subsequent "
+            "apm install runs on this host. "
+            "Prefer APM_ALLOW_PROTOCOL_FALLBACK=1 as an invocation-scoped alternative."
+        )
 
 
 @config.command(help="Get a configuration value")
@@ -299,21 +315,30 @@ def get(key):
             )
             sys.exit(1)
         value = getter()
-        click.echo(f"{key}: {value}")
+        # Render booleans as lowercase true/false (npm convention).
+        if isinstance(value, bool):
+            click.echo(f"{key}: {str(value).lower()}")
+        else:
+            click.echo(f"{key}: {value}")
     else:
         # Show all user-settable keys with their effective values (including
         # defaults).  Iterating raw config keys would hide settings that
         # have not been written yet (e.g. auto_integrate on a fresh install).
         from ..config import get_allow_protocol_fallback, get_prefer_ssh
 
         logger.progress("APM Configuration:")
-        click.echo(f"  auto-integrate: {get_auto_integrate()}")
+        click.echo(f"  auto-integrate: {str(get_auto_integrate()).lower()}")
         temp_dir = get_temp_dir()
         click.echo(
             f"  temp-dir: {temp_dir if temp_dir is not None else 'Not set (using system default)'}"
         )
-        click.echo(f"  allow-protocol-fallback: {get_allow_protocol_fallback()}")
-        click.echo(f"  prefer-ssh: {get_prefer_ssh()}")
+        # Only show transport keys when non-default to reduce noise.
+        _apf_val = get_allow_protocol_fallback()
+        _ssh_val = get_prefer_ssh()
+        if _apf_val:
+            click.echo("  allow-protocol-fallback: true")
+        if _ssh_val:
+            click.echo("  prefer-ssh: true")
 
         from ..core.experimental import is_enabled as _is_enabled_get
 

src/apm_cli/config.py

@@ -1,5 +1,6 @@
 """Configuration management for APM."""
 
+import contextlib
 import json
 import os
 from typing import Optional  # noqa: F401
@@ -18,13 +19,21 @@
 
 
 def ensure_config_exists():
-    """Ensure the configuration directory and file exist."""
+    """Ensure the configuration directory and file exist.
+
+    The directory is created with mode ``0o700`` (owner-only) and the
+    initial config file with mode ``0o600`` to prevent other users on a
+    shared system from reading persisted tokens or transport preferences.
+    Both restrictions are silently ignored on Windows.
+    """
     if not os.path.exists(CONFIG_DIR):
-        os.makedirs(CONFIG_DIR)
+        os.makedirs(CONFIG_DIR, mode=0o700, exist_ok=True)
 
     if not os.path.exists(CONFIG_FILE):
         with open(CONFIG_FILE, "w", encoding="utf-8") as f:
             json.dump({"default_client": "vscode"}, f)
+        with contextlib.suppress(NotImplementedError):
+            os.chmod(CONFIG_FILE, 0o600)
 
 
 def get_config():
@@ -133,20 +142,32 @@ def set_temp_dir(path: str) -> None:
     update_config({"temp_dir": resolved})
 
 
-def unset_temp_dir() -> None:
-    """Remove the ``temp_dir`` key from the config file.
+def _unset_config_key(key: str) -> None:
+    """Remove *key* from the config file atomically.
 
-    No-op if the key is not present.
+    No-op when *key* is not present.  Invalidates the in-process cache
+    before and after the write so subsequent reads see the updated state.
+
+    Args:
+        key: The JSON key to remove from ``~/.apm/config.json``.
     """
     _invalidate_config_cache()
     config = get_config()
-    if "temp_dir" in config:
-        del config["temp_dir"]
+    if key in config:
+        del config[key]
         with open(CONFIG_FILE, "w", encoding="utf-8") as f:
             json.dump(config, f, indent=2)
     _invalidate_config_cache()
 
 
+def unset_temp_dir() -> None:
+    """Remove the ``temp_dir`` key from the config file.
+
+    No-op if the key is not present.
+    """
+    _unset_config_key("temp_dir")
+
+
 # ---------------------------------------------------------------------------
 # Protocol transport preferences (issue #1243)
 # ---------------------------------------------------------------------------
@@ -196,13 +217,7 @@ def unset_allow_protocol_fallback() -> None:
     ``APM_ALLOW_PROTOCOL_FALLBACK`` env var and then the built-in
     default (``False``).
     """
-    _invalidate_config_cache()
-    config = get_config()
-    if "allow_protocol_fallback" in config:
-        del config["allow_protocol_fallback"]
-        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
-            json.dump(config, f, indent=2)
-    _invalidate_config_cache()
+    _unset_config_key("allow_protocol_fallback")
 
 
 def unset_prefer_ssh() -> None:
@@ -212,13 +227,7 @@ def unset_prefer_ssh() -> None:
     :func:`get_apm_protocol_pref` will fall through to the
     ``APM_GIT_PROTOCOL`` env var and then the built-in default (``None``).
     """
-    _invalidate_config_cache()
-    config = get_config()
-    if "prefer_ssh" in config:
-        del config["prefer_ssh"]
-        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
-            json.dump(config, f, indent=2)
-    _invalidate_config_cache()
+    _unset_config_key("prefer_ssh")
 
 
 def _parse_allow_protocol_fallback_env(raw: str | None) -> bool | None:
@@ -325,13 +334,7 @@ def unset_copilot_cowork_skills_dir() -> None:
 
     No-op if the key is not present.
     """
-    _invalidate_config_cache()
-    config = get_config()
-    if "copilot_cowork_skills_dir" in config:
-        del config["copilot_cowork_skills_dir"]
-        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
-            json.dump(config, f, indent=2)
-    _invalidate_config_cache()
+    _unset_config_key("copilot_cowork_skills_dir")
 
 
 def get_apm_temp_dir() -> str | None:

src/apm_cli/deps/github_downloader.py

@@ -170,10 +170,14 @@ def __init__(
             transport_selector: TransportSelector for protocol decisions.
                 Defaults to a new selector with GitConfigInsteadOfResolver.
             protocol_pref: User-stated transport preference for shorthand
-                deps. When None, reads APM_GIT_PROTOCOL env.
+                deps. When None, resolved from ``APM_GIT_PROTOCOL`` env var,
+                then ``prefer-ssh`` in ``~/.apm/config.json``, then ``None``
+                (let git insteadOf rules decide).
             allow_fallback: When True, permits cross-protocol fallback
-                (legacy behavior). When None, reads
-                APM_ALLOW_PROTOCOL_FALLBACK env.
+                (legacy behavior). When None, resolved from
+                ``APM_ALLOW_PROTOCOL_FALLBACK`` env var, then
+                ``allow-protocol-fallback`` in ``~/.apm/config.json``,
+                then ``False``.
         """
         self.auth_resolver = auth_resolver or AuthResolver()
         self.token_manager = self.auth_resolver._token_manager  # Backward compat

src/apm_cli/deps/transport_selection.py

@@ -30,7 +30,8 @@
 # Documented escape-hatch hint surfaced on strict-mode failures.
 FALLBACK_HINT = (
     "To allow cross-protocol fallback (not recommended), pass "
-    "--allow-protocol-fallback or set APM_ALLOW_PROTOCOL_FALLBACK=1."
+    "--allow-protocol-fallback, set APM_ALLOW_PROTOCOL_FALLBACK=1, "
+    "or run: apm config set allow-protocol-fallback true"
 )
 
 

src/apm_cli/install/validation.py

@@ -314,7 +314,7 @@ def _warn(msg: str) -> None:
             # the clone path honors) restores the legacy permissive chain.
             from apm_cli.config import get_apm_allow_protocol_fallback
 
-            allow_fallback_env = get_apm_allow_protocol_fallback()
+            allow_fallback = get_apm_allow_protocol_fallback()
 
             # For generic hosts (not GitHub, not ADO), relax the env so native
             # credential helpers (macOS Keychain, credential-store,
@@ -349,11 +349,9 @@ def _warn(msg: str) -> None:
                     dep_ref.repo_url, use_ssh=True, dep_ref=dep_ref
                 )
                 if explicit_scheme in ("http", "https"):
-                    urls_to_try = (
-                        [package_url] if not allow_fallback_env else [package_url, ssh_url]
-                    )
+                    urls_to_try = [package_url] if not allow_fallback else [package_url, ssh_url]
                 elif explicit_scheme == "ssh":
-                    urls_to_try = [ssh_url] if not allow_fallback_env else [ssh_url, package_url]
+                    urls_to_try = [ssh_url] if not allow_fallback else [ssh_url, package_url]
                 else:
                     # Shorthand has no user-stated transport; keep the legacy
                     # SSH-first chain so existing flows (e.g. SSH-key users on