netbox-super-cli 1.0.2__tar.gz → 1.0.3__tar.gz

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/AGENTS.md

@@ -50,6 +50,19 @@ short-lived feature branches (`fix/<slug>`, `feat/<slug>`, `docs/<slug>`,
 Releases are *tags* on `main`, not branches. Full convention:
 [`docs/contributing/branching.md`](docs/contributing/branching.md).
 
+## Coordinating work on issues and PRs
+
+When you start working on a GitHub issue or PR, post a comment so other agents (and humans) can see it's actively being worked. Use `gh issue comment <n> -b "..."` or `gh pr comment <n> -b "..."`.
+
+Required updates:
+
+- **On claim (start)** — before you begin, check existing comments. If someone else has claimed within the last 24h and has not posted a blocker/handoff, stop and surface the conflict to the user. Otherwise post a claim: what you're doing, branch name (if known), expected scope.
+- **On milestones** — branch pushed, PR opened, CI green, review requested. One short line each.
+- **On blockers** — when paused, blocked on input, or handing off. State *why* and what's needed to resume.
+- **On completion** — when merged, closed, or abandoning. Final status so the next agent doesn't re-investigate.
+
+Keep comments terse (1–3 lines). Sign with the agent identity already used in commits (e.g. `Co-Authored-By` line not needed in comments). Don't spam — skip a milestone update if the previous one is under ~5 minutes old and nothing materially changed.
+
 ## Where the design lives
 
 - `docs/superpowers/specs/2026-04-30-netbox-super-cli-design.md` — the full design.

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to netbox-super-cli are tracked here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely. From v1.0.0 onward, releases follow [Semantic Versioning](https://semver.org/) and the version in `pyproject.toml` matches the git tag. Pre-1.0 milestones (Phase 1-5) were pinned by tag while `pyproject.toml` stayed at `0.0.1`.
 
+## v1.0.3 — 2026-05-07
+
+Third patch release. Headline changes: `nsc login --new` now prompts to fetch the live schema (issue #32), the schema TTL fast-path self-heals on hash-confirmed fetches (issue #39), and bundled schemas are updated to 4.5.10 and 4.6.0.
+
+### Added
+
+- **`nsc login --new` prompts to fetch the live schema** (issue #32, PR #44). After a new profile is created, `nsc login` asks whether to fetch the live OpenAPI spec immediately. Answering yes primes the schema cache so the next command skips the bootstrap fetch entirely.
+- **`nsc skill export <dir>`** (PR #37). Copies the bundled `SKILL.md` to an arbitrary directory so it can be dropped into any agent harness without `nsc` on the `PATH`. Useful in CI or shared-skill repos where the package is not installed globally.
+- **Bundled schemas updated** (PR #36). Ships 4.5.10 and 4.6.0; drops the 4.6.0-beta2 snapshot. Offline fallback is now available for both stable release lines.
+
+### Fixed
+
+- **Schema TTL fast-path now self-heals after a hash-confirmed fetch** (issue #39). When `nsc` fetched `/api/schema/` and the live hash matched an existing cache file, it returned the cached `CommandModel` without bumping the sidecar's `fetched_at`. So an aged-out sidecar — or a legacy cache from before the sidecar feature — never gained proof of freshness and every subsequent invocation refetched the schema, defeating the v1.0.2 fast-path. `_build_and_cache` now calls a new `CacheStore.touch_fetched_at` to refresh (or seed) the sidecar after any successful live fetch, so the next invocation hits the fast path.
+
+### Documentation
+
+- Bundled Skill (`skills/netbox-super-cli/SKILL.md`) gained a scope-then-filter pattern for multi-device bulk reads (PR #41). The guidance shows how to narrow with `--site`, `--rack`, or `--role` before applying `--filter`, avoiding a full-table scan on large NetBox instances.
+
 ## v1.0.2 — 2026-05-07
 
 Second patch release. Headline change is the schema TTL fast-path (issue #34), which eliminates the per-invocation `GET /api/schema/` round-trip on warm caches. Also includes a small `nsc init` UX addition (verify_ssl prompt) and the documentation pass that landed since v1.0.1.

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/CLAUDE.md

@@ -43,6 +43,19 @@ short-lived feature branches (`fix/<slug>`, `feat/<slug>`, `docs/<slug>`,
 Releases are *tags* on `main`, not branches. Full convention:
 [`docs/contributing/branching.md`](docs/contributing/branching.md).
 
+## Coordinating work on issues and PRs
+
+When you start working on a GitHub issue or PR, post a comment so other agents (and humans) can see it's actively being worked. Use `gh issue comment <n> -b "..."` or `gh pr comment <n> -b "..."`.
+
+Required updates:
+
+- **On claim (start)** — before you begin, check existing comments. If someone else has claimed within the last 24h and has not posted a blocker/handoff, stop and surface the conflict to the user. Otherwise post a claim: what you're doing, branch name (if known), expected scope.
+- **On milestones** — branch pushed, PR opened, CI green, review requested. One short line each.
+- **On blockers** — when paused, blocked on input, or handing off. State *why* and what's needed to resume.
+- **On completion** — when merged, closed, or abandoning. Final status so the next agent doesn't re-investigate.
+
+Keep comments terse (1–3 lines). Sign with the agent identity already used in commits (e.g. `Co-Authored-By` line not needed in comments). Don't spam — skip a milestone update if the previous one is under ~5 minutes old and nothing materially changed.
+
 ## Where the design lives
 
 - `docs/superpowers/specs/2026-04-30-netbox-super-cli-design.md` — the full design.

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-super-cli
-Version: 1.0.2
+Version: 1.0.3
 Summary: Dynamic NetBox CLI generated from the live OpenAPI schema.
 Project-URL: Homepage, https://github.com/thomaschristory/netbox-super-cli
 Project-URL: Issues, https://github.com/thomaschristory/netbox-super-cli/issues
@@ -126,7 +126,7 @@ The wire body sent to NetBox is **not** redacted — only the audit log. A faile
 
 ```sh
 # Dump every endpoint in the bundled NetBox schema as JSON.
-uv run nsc commands --schema nsc/schemas/bundled/netbox-4.6.0-beta2.json.gz --output json | head
+uv run nsc commands --schema nsc/schemas/bundled/netbox-4.6.0.json.gz --output json | head
 
 # Or against a live install.
 uv run nsc commands --schema https://netbox.example.com/api/schema/?format=json --output json

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/README.md

@@ -99,7 +99,7 @@ The wire body sent to NetBox is **not** redacted — only the audit log. A faile
 
 ```sh
 # Dump every endpoint in the bundled NetBox schema as JSON.
-uv run nsc commands --schema nsc/schemas/bundled/netbox-4.6.0-beta2.json.gz --output json | head
+uv run nsc commands --schema nsc/schemas/bundled/netbox-4.6.0.json.gz --output json | head
 
 # Or against a live install.
 uv run nsc commands --schema https://netbox.example.com/api/schema/?format=json --output json

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/docs/contributing/adding-bundled-schemas.md

@@ -9,7 +9,7 @@ the repo and shipped inside the wheel.
 ```
 nsc/schemas/bundled/
 ├── manifest.yaml
-├── netbox-4.6.0-beta2.json.gz
+├── netbox-4.6.0.json.gz
 └── netbox-<other-version>.json.gz
 ```
 
@@ -17,8 +17,8 @@ nsc/schemas/bundled/
 
 ```yaml
 schemas:
-  - version: "4.6.0-beta2"
-    file: "netbox-4.6.0-beta2.json.gz"
+  - version: "4.6.0"
+    file: "netbox-4.6.0.json.gz"
 ```
 
 ## Adding a new version

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/docs/getting-started/install.md

@@ -56,5 +56,5 @@ Restart your shell, then verify with `nsc <TAB><TAB>`.
 ## Requirements
 
 - Python ≥ 3.12.
-- A reachable NetBox install (any version with `/api/schema/` enabled — 4.4+).
+- A reachable NetBox install (any version with `/api/schema/` enabled — 4.5+).
 - A NetBox API token (read-only is enough for read commands; writable for `--apply`).

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/docs/index.md

@@ -1,7 +1,7 @@
 # netbox-super-cli
 
 Dynamic NetBox CLI driven by the live OpenAPI schema. The same `nsc` binary works
-against any NetBox version (4.4+) and exposes plugin-provided endpoints automatically
+against any NetBox version (4.5+) and exposes plugin-provided endpoints automatically
 because the schema — not hand-written code — defines the surface.
 
 ## Why nsc

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/docs/reference/cli.md

@@ -2,7 +2,7 @@
 
 <!-- This file is auto-generated by `scripts/gen_docs.py`. Do not edit by hand — re-run the generator instead. -->
 
-Generated from `netbox-4.6.0-beta2.json.gz` (NetBox `4.6.0-beta2 (4.6)`).
+Generated from `netbox-4.6.0.json.gz` (NetBox `4.6.0-Docker-5.0.1 (4.6)`).
 
 Every endpoint exposed by NetBox surfaces as `nsc <tag> <resource> <verb>`.
 Verbs are derived from the `operationId`: `list`, `get`, `create`, `update`, `replace`, `delete`,

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/docs/reference/schemas.md

@@ -7,4 +7,5 @@ fallback when a live schema can't be fetched and no per-profile cache exists.
 
 | Version | File |
 |---|---|
-| `4.6.0-beta2` | `netbox-4.6.0-beta2.json.gz` |
+| `4.5.10` | `netbox-4.5.10.json.gz` |
+| `4.6.0` | `netbox-4.6.0.json.gz` |

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/nsc/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/nsc/cache/store.py

@@ -87,6 +87,28 @@ class CacheStore:
         _atomic_write(meta, json.dumps({"fetched_at": time.time()}))
         return target
 
+    def touch_fetched_at(self, profile: str, schema_hash: str) -> None:
+        """Bump only the sidecar's `fetched_at` to now, without rewriting
+        the cache file. Called after a live fetch confirms an existing
+        cache entry is still valid (its hash matches): we want the TTL
+        fast-path to trust it on the next invocation, but the JSON body
+        on disk is byte-identical so re-serializing it is wasteful.
+
+        Also seeds a sidecar for caches written before #35 (legacy
+        upgrade path) — without this, those entries never gain proof of
+        freshness and every invocation refetches `/api/schema/` even
+        though the schema is unchanged. No-op when the cache file is
+        missing (don't leave an orphaned sidecar)."""
+        self._validate_profile(profile)
+        if not _HASH_RE.match(schema_hash):
+            return
+        target = self._path_for(profile, schema_hash)
+        if not target.exists():
+            return
+        meta = self._meta_path_for(profile, schema_hash)
+        meta.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write(meta, json.dumps({"fetched_at": time.time()}))
+
     def load_fetched_at(self, profile: str, schema_hash: str) -> float | None:
         """Return epoch seconds when this cache entry was last fetched, or
         `None` if the sidecar is missing/unreadable. Used by the TTL

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/nsc/cli/login_commands.py

@@ -19,7 +19,7 @@ import typer
 from ruamel.yaml.comments import CommentedMap, TaggedScalar
 
 from nsc.auth.verify import VerifyError, verify
-from nsc.cli.runtime import emit_envelope
+from nsc.cli.runtime import ResolvedProfile, emit_envelope
 from nsc.config.loader import ConfigParseError, load_config
 from nsc.config.models import OutputFormat, Profile
 from nsc.config.settings import default_paths
@@ -30,6 +30,7 @@ from nsc.config.writer import (
     load_round_trip,
 )
 from nsc.output.errors import ErrorEnvelope, ErrorType
+from nsc.schema.source import resolve_command_model
 
 
 def _config_path() -> Path:
@@ -117,6 +118,33 @@ def _print_success(username: str, version: str) -> None:
     typer.echo(f"✓ authenticated as {username}, NetBox {version}")
 
 
+def _fetch_schema_for_login(profile: Profile, token: str) -> None:
+    rp = ResolvedProfile(
+        name=profile.name,
+        url=profile.url,
+        token=token,
+        verify_ssl=profile.verify_ssl,
+        timeout=profile.timeout if profile.timeout is not None else 30.0,
+        schema_url=profile.schema_url,
+    )
+    schema_url = (
+        str(rp.schema_url)
+        if rp.schema_url is not None
+        else f"{str(rp.url).rstrip('/')}/api/schema/?format=json"
+    )
+    typer.echo(f"Fetching schema from {schema_url} ...")
+    try:
+        resolve_command_model(
+            paths=default_paths(),
+            profile=rp,
+            schema_override=None,
+            force_refresh=True,
+        )
+        typer.echo("Schema cached.")
+    except Exception as exc:
+        typer.echo(f"Warning: schema fetch failed ({exc}); skipping.", err=True)
+
+
 def register(app: typer.Typer) -> None:
     @app.command("login", help="Verify / create / rotate a profile's token.")
     def login_cmd(
@@ -136,20 +164,27 @@ def register(app: typer.Typer) -> None:
                 help="Environment variable name (required when --store=env).",
             ),
         ] = None,
+        fetch_schema: Annotated[
+            bool,
+            typer.Option(
+                "--fetch-schema",
+                help="Fetch and cache the live OpenAPI schema (applies to verify and --new).",
+            ),
+        ] = False,
     ) -> None:
         if new and rotate:
             raise typer.BadParameter("--new and --rotate are mutually exclusive")
 
         if new:
-            _do_login_new(profile, url, store, env_var)
+            _do_login_new(profile, url, store, env_var, fetch_schema=fetch_schema)
             return
         if rotate:
             _do_login_rotate(profile, store, env_var)
             return
-        _do_login_verify(profile)
+        _do_login_verify(profile, fetch_schema=fetch_schema)
 
 
-def _do_login_verify(profile_name: str | None) -> None:
+def _do_login_verify(profile_name: str | None, *, fetch_schema: bool = False) -> None:
     try:
         config = load_config(_config_path())
     except ConfigParseError as exc:
@@ -173,6 +208,12 @@ def _do_login_verify(profile_name: str | None) -> None:
         )
         raise typer.Exit(code=code) from exc
     _print_success(result.username, result.netbox_version)
+    if fetch_schema:
+        token = profile.token
+        if token is None:
+            typer.echo("Warning: token not available from config; skipping schema fetch.", err=True)
+            return
+        _fetch_schema_for_login(profile, token)
 
 
 def _do_login_new(
@@ -180,6 +221,8 @@ def _do_login_new(
     url: str | None,
     store: str,
     env_var: str | None,
+    *,
+    fetch_schema: bool = False,
 ) -> None:
     if profile_name is None:
         raise typer.BadParameter("--new requires --profile <name>")
@@ -224,6 +267,8 @@ def _do_login_new(
         set_default=set_default,
     )
     _print_success(result.username, result.netbox_version)
+    if fetch_schema or typer.confirm("Fetch and cache the live schema now?", default=True):
+        _fetch_schema_for_login(candidate, token_for_verify)
 
 
 def _do_login_rotate(

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/nsc/cli/skill_commands.py

@@ -141,6 +141,30 @@ def _render_json(resolution: _Resolution, mode: str, written: bool, source: Path
     return json.dumps(payload)
 
 
+def _render_export_table(dest_file: Path, source: Path, mode: str, written: bool) -> str:
+    lines: list[str] = []
+    if mode == "dry-run":
+        lines.append("nsc skill export (dry-run) — pass --apply to write")
+        lines.append(f"  would write to {dest_file}")
+        lines.append(f"  source: {source}")
+    elif written:
+        lines.append(f"✓ exported netbox-super-cli skill to {dest_file}")
+    else:
+        lines.append("nsc skill export (no-op)")
+    return "\n".join(lines)
+
+
+def _render_export_json(dest_file: Path, source: Path, mode: str, written: bool) -> str:
+    payload: dict[str, object] = {
+        "mode": mode,
+        "destination": str(dest_file),
+        "source": str(source),
+    }
+    if mode == "apply":
+        payload["written"] = written
+    return json.dumps(payload)
+
+
 def register(app: typer.Typer) -> None:
     skill_app = typer.Typer(
         name="skill",
@@ -183,4 +207,39 @@ def register(app: typer.Typer) -> None:
             else:
                 typer.echo(_render_table(resolution, mode, written, source))
 
+    @skill_app.command("export")
+    def export_cmd(
+        destination: Annotated[
+            Path,
+            typer.Argument(
+                help=(
+                    "Directory to export the skill into. The skill is written "
+                    "to <destination>/netbox-super-cli/SKILL.md."
+                ),
+            ),
+        ],
+        apply_: Annotated[
+            bool,
+            typer.Option("--apply", help="Actually copy the file (default: dry-run)."),
+        ] = False,
+        output: Annotated[
+            _OutputFormat,
+            typer.Option("--output", "-o", help="table|json"),
+        ] = _OutputFormat.TABLE,
+    ) -> None:
+        dest_file = (destination.expanduser() / BUNDLE_NAME / "SKILL.md").resolve()
+        mode = "apply" if apply_ else "dry-run"
+        written = False
+
+        with bundle_path() as source:
+            if apply_:
+                dest_file.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source, dest_file)
+                written = True
+
+            if output is _OutputFormat.JSON:
+                typer.echo(_render_export_json(dest_file, source, mode, written))
+            else:
+                typer.echo(_render_export_table(dest_file, source, mode, written))
+
     app.add_typer(skill_app, name="skill")

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/nsc/schema/source.py

@@ -20,6 +20,7 @@ import time
 from pathlib import Path
 
 import httpx
+from ruamel.yaml import YAML
 
 from nsc.builder.build import build_command_model
 from nsc.cache.store import CacheStore
@@ -124,6 +125,12 @@ def _build_and_cache(loaded: LoadedSchema, paths: Paths, profile: ResolvedProfil
     store = CacheStore(root=paths.cache_dir)
     cached = store.load(profile.name, loaded.hash)
     if cached is not None:
+        # Issue #39: a live fetch just confirmed this hash is current.
+        # Bump the sidecar so the TTL fast-path trusts the cache on the
+        # next invocation, otherwise an aged-out sidecar (or a legacy
+        # cache from before sidecars existed) makes us refetch every
+        # invocation even though the schema hasn't moved.
+        store.touch_fetched_at(profile.name, loaded.hash)
         return cached
     model = build_command_model(loaded)
     store.save(profile.name, model)
@@ -201,8 +208,16 @@ def _find_fresh_cached(
 
 def _load_bundled_command_model() -> CommandModel | None:
     pkg_dir = Path(_bundled_pkg.__file__).resolve().parent
-    candidates = sorted(list(pkg_dir.glob("*.json")) + list(pkg_dir.glob("*.json.gz")))
-    if not candidates:
+    manifest_path = pkg_dir / "manifest.yaml"
+    if not manifest_path.exists():
         return None
-    loaded = load_schema(str(candidates[0]))
+    manifest = YAML(typ="safe").load(manifest_path.read_text())
+    schemas = manifest.get("schemas") if isinstance(manifest, dict) else None
+    if not schemas:
+        return None
+    newest = schemas[-1]
+    schema_path = pkg_dir / str(newest["file"])
+    if not schema_path.exists():
+        return None
+    loaded = load_schema(str(schema_path))
     return build_command_model(loaded)

netbox_super_cli-1.0.3/nsc/schemas/bundled/manifest.yaml

@@ -0,0 +1,9 @@
+# Bundled NetBox OpenAPI snapshots. Newest entry last.
+# When the offline fallback fires, `nsc/schema/source.py` loads the last
+# entry; `scripts/gen_docs.py` does the same for the auto-generated CLI
+# reference. To add a new version, see docs/contributing/adding-bundled-schemas.md.
+schemas:
+  - version: "4.5.10"
+    file: "netbox-4.5.10.json.gz"
+  - version: "4.6.0"
+    file: "netbox-4.6.0.json.gz"

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "netbox-super-cli"
-version = "1.0.2"
+version = "1.0.3"
 description = "Dynamic NetBox CLI generated from the live OpenAPI schema."
 readme = "README.md"
 requires-python = ">=3.12"

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/skills/netbox-super-cli/SKILL.md

@@ -115,6 +115,29 @@ operation.
   nsc dcim interfaces list --device 42 --all --output json \
     | jq '[.[] | select(.enabled == true and (.name | startswith("Gi")))]'
   ```
+- **Working across many devices? Scope once, filter locally.** Don't
+  loop `nsc dcim interfaces list --device <id>` over every device — pull
+  the broadest reasonable scope (a site, a role, a device type) in a
+  single call, then narrow with `jq`. Server-side filters compose, so
+  pick the tightest scope NetBox can apply for you:
+  ```bash
+  # GOOD — one call scoped to a site, local filtering by device list
+  nsc dcim interfaces list --site dc1 --all --output json \
+    | jq --argjson ids '[42, 43, 44]' \
+        '[.[] | select(.device.id as $d | $ids | index($d))]'
+
+  # GOOD — one call scoped to a role, then group by device
+  nsc dcim interfaces list --device_role leaf-switch --all --output json \
+    | jq 'group_by(.device.name)'
+
+  # BAD — N round-trips, one per device
+  for id in 42 43 44; do
+    nsc dcim interfaces list --device "$id" --all --output json
+  done
+  ```
+  The same pattern applies to IPs, cables, inventory items, and any
+  child resource: filter by the parent scope (site, tenant, role,
+  device-type), fetch once, partition locally.
 - **Pagination defaults:** `list` returns the first page (50 rows by
   default). Pass `--all` to follow `next` links until exhausted, or
   `--limit N` for a hard cap. `nsc describe <tag> <resource>` reveals

{netbox_super_cli-1.0.2 → netbox_super_cli-1.0.3}/tests/cache/test_store.py

@@ -157,3 +157,63 @@ def test_load_fetched_at_handles_corrupt_sidecar(tmp_path: Path) -> None:
     sidecar = tmp_path / "prod" / ("a" * 64 + ".meta.json")
     sidecar.write_text("not json")
     assert store.load_fetched_at("prod", "a" * 64) is None
+
+
+def test_touch_fetched_at_refreshes_existing_sidecar(tmp_path: Path) -> None:
+    """`touch_fetched_at` must update an existing sidecar's `fetched_at`
+    without rewriting the cache file. Used by the source resolver after
+    a live fetch confirms an existing-by-hash cache entry is still valid."""
+    store = CacheStore(root=tmp_path)
+    h = "a" * 64
+    store.save("prod", _model(h))
+    cache_file = tmp_path / "prod" / f"{h}.json"
+    original_cache_mtime = cache_file.stat().st_mtime
+
+    old_ts = time.time() - 10_000
+    sidecar = tmp_path / "prod" / f"{h}.meta.json"
+    sidecar.write_text(json.dumps({"fetched_at": old_ts}))
+
+    before = time.time()
+    store.touch_fetched_at("prod", h)
+    after = time.time()
+
+    assert cache_file.stat().st_mtime == original_cache_mtime
+    refreshed = json.loads(sidecar.read_text())["fetched_at"]
+    assert before <= refreshed <= after
+
+
+def test_touch_fetched_at_creates_sidecar_for_legacy_cache(tmp_path: Path) -> None:
+    """A cache file written before the sidecar feature has no
+    `<hash>.meta.json`. After a live fetch confirms the hash matches,
+    `touch_fetched_at` must create the sidecar so the next invocation
+    can use the TTL fast-path."""
+    store = CacheStore(root=tmp_path)
+    h = "a" * 64
+    store.save("prod", _model(h))
+    sidecar = tmp_path / "prod" / f"{h}.meta.json"
+    sidecar.unlink()
+
+    before = time.time()
+    store.touch_fetched_at("prod", h)
+    after = time.time()
+
+    assert sidecar.exists()
+    fetched_at = json.loads(sidecar.read_text())["fetched_at"]
+    assert before <= fetched_at <= after
+
+
+def test_touch_fetched_at_noop_when_cache_file_missing(tmp_path: Path) -> None:
+    """No cache file means there is nothing to mark fresh — must not
+    create an orphaned sidecar."""
+    store = CacheStore(root=tmp_path)
+    h = "a" * 64
+    store.touch_fetched_at("prod", h)
+    sidecar = tmp_path / "prod" / f"{h}.meta.json"
+    assert not sidecar.exists()
+
+
+def test_touch_fetched_at_rejects_invalid_hash(tmp_path: Path) -> None:
+    store = CacheStore(root=tmp_path)
+    store.touch_fetched_at("prod", "not-a-hash")
+    profile_dir = tmp_path / "prod"
+    assert not profile_dir.exists() or not any(profile_dir.iterdir())