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

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

@@ -2,14 +2,27 @@
 
 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.4 — 2026-05-16
+
+Maintenance release: a codebase-wide internal simplification pass (no behavioural change), a full documentation parity audit, and a dependency bump. There are no CLI, config, or output-contract changes — upgrading from v1.0.3 is transparent.
+
+### Changed
+
+- **Codebase-wide simplification pass** (PRs #61–#71). Every package was audited to remove dead code, tighten types, and drop unreachable branches: schema parsing (#61), cache store & schema source (#62), output (#63), command model / alias resolver / auth verify (#64), config (#65), http (#66), cli (#68), builder (#69), top-level package files (#70), and the cli writes pipeline (#71). These are internal-only changes — the public CLI surface, command tree, error envelope, and exit codes are unchanged and remain covered by the existing test suite.
+- Bumped `urllib3` 2.6.3 → 2.7.0 (PR #46).
+
+### Documentation
+
+- **Full documentation parity audit** (PR #73). Every hand-written user-facing and contributor page, plus the bundled `SKILL.md`, was audited file-by-file against the current code and corrected. Notable fixes: removed references to non-existent `nsc describe` / `nsc refresh` commands; documented the real `replace` (PUT) verb; corrected the HTTP retry policy (writes are never retried on 5xx); corrected the schema-cache invalidation model to the TTL fast-path; documented `nsc skill export`, `nsc login --fetch-schema`, and the post-`login --new` schema-fetch prompt; and corrected exit-code semantics (a malformed single JSON/YAML input is a `client`/exit-6 error — only a bad NDJSON line is `input_error`/exit 4). Auto-generated reference pages were verified current.
+
 ## 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.
+- **`nsc login --new` prompts to fetch the live schema** (issue #32, PR #44). After a new profile is created, `nsc login` asks `Fetch and cache the live schema now?` (defaults `Y`) and fetches if accepted. A new `nsc login --fetch-schema` flag fetches unconditionally (no prompt) and also applies to the bare/`--profile` verify path. Either way the schema is fetched with a forced refresh, priming the cache so the next command skips the bootstrap fetch entirely. `--rotate` does not prompt for or fetch the schema.
+- **`nsc skill export <dir>`** (PR #37). Copies the bundled `SKILL.md` into `<dir>/netbox-super-cli/SKILL.md` so it can be dropped into any agent harness without `nsc` on the `PATH`. Dry-run by default (prints the would-write path); `--apply` actually copies. `--output json` emits a structured envelope. 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-super-cli
-Version: 1.0.3
+Version: 1.0.4
 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
@@ -171,11 +171,17 @@ JSON output, error envelope, audit log).
 ```sh
 nsc skill install --target claude-code            # dry-run; prints the destination
 nsc skill install --target claude-code --apply    # actually copies
+
+# Or export to an arbitrary directory (e.g. CI or a shared-skill repo).
+nsc skill export ./skills                          # dry-run; prints the would-write path
+nsc skill export ./skills --apply                  # writes ./skills/netbox-super-cli/SKILL.md
 ```
 
-Targets: `claude-code`, `codex`, `gemini`, `copilot`. Where a target has no
-documented programmatic install path, the helper prints actionable manual
-instructions instead of guessing.
+`skill install` targets: `claude-code`, `codex`, `gemini`, `copilot`. Where a
+target has no documented programmatic install path, the helper prints actionable
+manual instructions instead of guessing. `skill export <dir>` always writes to
+`<dir>/netbox-super-cli/SKILL.md` and, like `install`, is dry-run unless you
+pass `--apply`.
 
 ## License
 

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

@@ -144,11 +144,17 @@ JSON output, error envelope, audit log).
 ```sh
 nsc skill install --target claude-code            # dry-run; prints the destination
 nsc skill install --target claude-code --apply    # actually copies
+
+# Or export to an arbitrary directory (e.g. CI or a shared-skill repo).
+nsc skill export ./skills                          # dry-run; prints the would-write path
+nsc skill export ./skills --apply                  # writes ./skills/netbox-super-cli/SKILL.md
 ```
 
-Targets: `claude-code`, `codex`, `gemini`, `copilot`. Where a target has no
-documented programmatic install path, the helper prints actionable manual
-instructions instead of guessing.
+`skill install` targets: `claude-code`, `codex`, `gemini`, `copilot`. Where a
+target has no documented programmatic install path, the helper prints actionable
+manual instructions instead of guessing. `skill export <dir>` always writes to
+`<dir>/netbox-super-cli/SKILL.md` and, like `install`, is dry-run unless you
+pass `--apply`.
 
 ## License
 

netbox_super_cli-1.0.4/docs/architecture/caching.md

@@ -0,0 +1,72 @@
+# Caching
+
+`~/.nsc/` holds all on-disk state. Bundled schemas live inside the installed
+wheel and are NOT copied into `~/.nsc/`.
+
+## Layout
+
+```
+~/.nsc/
+├── config.yaml
+├── cache/
+│   ├── prod/<schema-hash>.json         # generated CommandModel
+│   ├── prod/<schema-hash>.meta.json    # sidecar: {"fetched_at": <epoch>}
+│   ├── lab/<schema-hash>.json
+│   └── adhoc/<schema-hash>.json        # env-var-only invocations
+└── logs/
+    ├── last-request.json               # most recent HTTP exchange (overwritten)
+    └── audit.jsonl                     # append-only mutation log
+                                        #   (rotated to audit.jsonl.1 at 10 MB)
+```
+
+The location root is `~/.nsc/` unless `NSC_HOME` is set, in which case it is
+`$NSC_HOME` (expanded and resolved).
+
+## Invalidation
+
+The cache is keyed by `sha256` of the canonicalized schema body. There are two
+distinct caches: this **command-model disk cache** (`<hash>.json`), and the
+**schema-source TTL fast-path** that decides whether to re-fetch the live
+schema at all.
+
+Invalidation is **TTL-gated**, not "every invocation". Under the default
+`daily` policy (`Defaults.schema_refresh = SchemaRefresh.DAILY`) `nsc` trusts
+the cached command-model — and skips the schema fetch entirely — as long as the
+profile's newest `<hash>.meta.json` sidecar `fetched_at` is within the policy's
+TTL. Only once the TTL has lapsed (or the policy forces it) does `nsc` re-fetch
+the live schema; a changed schema then produces a new hash and a new
+`<hash>.json`. Freshness is keyed off the sidecar's `fetched_at`, **not** the
+cache file's mtime, so a `touch`, backup-restore, or `cp -p` cannot fake
+freshness. A sidecar dated more than 60s in the future (clock skew or
+tampering) is rejected.
+
+When a live fetch returns a hash that is already cached, the sidecar's
+`fetched_at` is bumped (`CacheStore.touch_fetched_at`) so the TTL fast-path
+trusts the cache on the next invocation — this also self-heals legacy caches
+written before sidecars existed.
+
+Force a re-fetch sooner with the global `--refresh-schema` flag (bypasses the
+TTL fast-path under any policy) or `nsc login --fetch-schema`. The full policy
+table lives in [Schema loading](schema-loading.md#refresh-modes).
+
+## Cleaning up
+
+`nsc cache prune` handles three classes of orphan:
+
+1. Profile directories not in `~/.nsc/config.yaml` (e.g., a removed profile).
+2. `<schema_hash>.json` files inside an active profile whose hash no longer
+   matches the live schema. **Skipped per-profile when the profile is
+   offline** so a network blip never removes the offline fallback.
+3. With `--max-age <days>`: cache files older than the threshold (excludes
+   files already covered by rule 1).
+
+The `adhoc` cache is **never pruned automatically** — it represents valid
+env-var-only usage. Applying a prune also removes each deleted file's
+`<hash>.meta.json` sidecar.
+
+```sh
+nsc cache prune                      # dry-run
+nsc cache prune --apply              # actually delete
+nsc cache prune --max-age 30 --apply
+nsc cache prune --output json        # structured envelope
+```

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/architecture/command-generation.md

@@ -5,13 +5,13 @@
 ## The shape
 
 ```python
-CommandModel
+CommandModel(info_title, info_version, schema_hash, tags: dict[str, Tag])
 ├── tags: dict[str, Tag]
-│   └── Tag(name, resources: dict[str, Resource])
+│   └── Tag(name, description?, resources: dict[str, Resource])
 │       └── Resource(name, list_op?, get_op?, create_op?, update_op?, replace_op?,
 │                    delete_op?, custom_actions: list[Operation])
-└── Operation(operation_id, http_method, path, parameters, request_body?,
-              response_schema?, summary?)
+└── Operation(operation_id, http_method, path, summary?, description?,
+              parameters, request_body?, default_columns?)
 ```
 
 Pure Pydantic. JSON-serializable. Cached to disk.

netbox_super_cli-1.0.4/docs/architecture/http-client.md

@@ -0,0 +1,66 @@
+# HTTP client
+
+`nsc/http/` is a thin wrapper around `httpx.Client`.
+
+## What it adds
+
+- Token auth: `Authorization: Token <token>` header (plus
+  `Accept: application/json`), set once per Client.
+- Configurable `verify_ssl` and `timeout` (default 30s, from
+  `Defaults.timeout`).
+- Method-aware retries, up to 3 attempts with exponential backoff
+  (`base_delay` 0.5s, ±25% jitter):
+    - **Reads** (GET/HEAD/OPTIONS) retry on 5xx **and** on connect
+      failures.
+    - **Writes** (POST/PATCH/PUT/DELETE) retry **only** on a provable
+      connect failure (request never left the client). They are
+      **never** retried on 5xx, read-timeout, or ambiguous transport
+      errors — a write that may have reached the server is not replayed.
+  Every attempt is recorded as its own audit entry with `attempt_n` and
+  `final_attempt`; redaction is applied on every write, so a failed
+  retry never unredacts.
+- Pagination helper that follows `next` URLs (used by `--all`).
+- Audit log appender at `~/.nsc/logs/audit.jsonl` — written for writes
+  always, and for any request when `--debug` is set.
+- A "last request" snapshot at `~/.nsc/logs/last-request.json`
+  (overwritten every call, regardless of `--debug`) — handy for triage.
+
+## Auth and the bootstrap path
+
+A schema fetch may run before the first command request (only when the
+TTL fast-path misses — see [Caching](caching.md)); it uses its own
+short-lived `httpx.Client` in `nsc/schema/`, not this `NetBoxClient`.
+Command requests then go through a single `NetBoxClient` whose
+`httpx.Client` carries the auth header for the life of the process.
+Token rotation via `nsc login --rotate` does NOT invalidate the cached
+model (the schema hash is what keys the cache; the token never affected
+it).
+
+## Audit entry shape
+
+Each line of `audit.jsonl` is a JSON object with:
+
+- `schema_version`, `timestamp` (UTC ISO8601, `…Z`)
+- `operation_id`, `method`, `url`
+- `request.headers` (sensitive headers, incl. `Authorization`, rewritten
+  to `"<redacted>"` — the key stays, the value is masked)
+- `request.query`, `request.body` (sensitive `sensitive_paths` fields
+  rewritten to `"<redacted>"`); bodies over 256 KB collapse to
+  `{"_truncated": true, "_size_bytes": N}` with `request.body_truncated`
+- `response.status_code`, `response.headers`, `response.body` (same
+  256 KB truncation via `response.body_truncated`); `response` is `null`
+  on a transport failure
+- `duration_ms`, `attempt_n`, `final_attempt`, `error_kind`
+- `dry_run`, `preflight_blocked`, `record_indices`, `applied`, `explain`
+
+The audit file is append-only and rotates to `audit.jsonl.1` at 10 MB;
+failed writes do NOT unredact. See
+[Writes and safety](../guides/writes-and-safety.md) for the full redaction
+contract.
+
+## What it deliberately does not do
+
+- Async — sync only in v1, kept feasible by httpx if a future async path lands.
+- Connection pooling across profiles — each profile gets its own `Client`.
+- Caching responses — caching the command-model is enough; caching response
+  payloads would surprise users.

netbox_super_cli-1.0.4/docs/architecture/overview.md

@@ -0,0 +1,48 @@
+# Architecture overview
+
+`nsc` is layered around a framework-free "brain". The brain — schema parsing
+and the normalized command-model — knows nothing about Typer, Rich, or httpx.
+The CLI layer consumes the brain; a future TUI could too without changing the
+brain.
+
+```
+nsc/
+├── schema/          # OpenAPI fetching, hashing, parsing
+├── model/           # Normalized command-model (data only, framework-free)
+├── builder/         # Schema → CommandModel
+├── cli/             # Typer application; walks the model, registers commands
+├── http/            # Thin httpx wrapper: auth, retries, audit
+├── output/          # Formatters (table/json/jsonl/yaml/csv) + error envelope
+├── config/          # Pydantic config models + ruamel.yaml writer
+├── cache/           # On-disk cache for generated CommandModels
+├── auth/            # Login verification helpers (verify probe, token rotate)
+├── aliases/         # Curated alias resolver (ls/get/rm/search)
+├── skill/           # Bundle-path helper for the portable SKILL.md
+└── schemas/bundled/ # Versioned NetBox OpenAPI snapshots (offline fallback)
+```
+
+## The hard rule
+
+`nsc/model/` imports nothing from `nsc/cli/`, `nsc/http/`, or any framework.
+If you need to add a dependency to `model/`, you're solving the wrong problem.
+
+## Data flow at runtime
+
+1. `nsc` startup → resolve profile (CLI flags > env > config > adhoc).
+2. Resolve schema source (`--schema` override > fresh cache within the
+   TTL policy > live fetch > stale cache > bundled fallback).
+3. Hash + parse → build the command-model (or load cached).
+4. Hand model to Typer; register commands dynamically.
+5. Dispatch.
+6. `http/` executes (or shows dry-run).
+7. `output/` renders.
+
+## Where to read next
+
+- [Schema loading](schema-loading.md) — fetch, hash, fallback chain.
+- [Command generation](command-generation.md) — how `operationId` becomes a verb.
+- [HTTP client](http-client.md) — auth, retries, audit log.
+- [Caching](caching.md) — disk layout, invalidation.
+
+For the full design rationale, see the specs in `docs/superpowers/specs/` (in
+the repo, not in this site — the planning artifacts are local-only).

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/architecture/schema-loading.md

@@ -18,10 +18,13 @@ and an optional `--refresh-schema` override:
    `{profile.url}/api/schema/?format=json`. The fetched body is hashed;
    if a cache file already exists at that hash it's loaded directly,
    otherwise the command-model is rebuilt and saved.
-4. On fetch failure: any cached entry for the profile (warns once on
-   stderr).
-5. Bundled snapshot at `nsc/schemas/bundled/netbox-<closest-version>.json`
-   (shipped in the wheel) — last-resort offline fallback.
+4. On fetch failure: the newest valid cached entry for the profile
+   (warns once on stderr), sorted by mtime.
+5. Bundled snapshot — the **last (newest) entry** in
+   `nsc/schemas/bundled/manifest.yaml` (currently
+   `netbox-4.6.0.json.gz`), shipped in the wheel. This is the
+   last-resort offline fallback; it is *not* version-matched to the
+   unreachable instance.
 
 ## Hashing
 
@@ -49,12 +52,12 @@ that's the upgrade path for caches written before sidecars existed.
 
 ## Offline behavior
 
-- Live schema unreachable + cache present → use cache, warn once on
-  stderr.
-- Live schema unreachable + no cache → fall back to the closest bundled
-  version, warn loudly.
-- All such errors include a remediation hint pointing at
-  `--refresh-schema` for once the instance is reachable again.
+- Live schema unreachable + cache present → use the newest valid cached
+  entry, warn once on stderr.
+- Live schema unreachable + no cache → fall back to the newest bundled
+  snapshot (last manifest entry), warn once on stderr.
+- Neither cache nor bundled snapshot available → `SchemaSourceError`
+  (exit 3).
 
 ## Refresh modes
 

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

@@ -9,14 +9,16 @@ the repo and shipped inside the wheel.
 ```
 nsc/schemas/bundled/
 ├── manifest.yaml
-├── netbox-4.6.0.json.gz
-└── netbox-<other-version>.json.gz
+├── netbox-4.5.10.json.gz
+└── netbox-4.6.0.json.gz
 ```
 
-`manifest.yaml`:
+`manifest.yaml` (newest entry last):
 
 ```yaml
 schemas:
+  - version: "4.5.10"
+    file: "netbox-4.5.10.json.gz"
   - version: "4.6.0"
     file: "netbox-4.6.0.json.gz"
 ```
@@ -56,6 +58,9 @@ versions when they're no longer cited by any active deployment.
 
 1. **First-run offline.** A new install with no cache, no network — the user
    gets a usable command tree from the bundled schema.
-2. **CI without a NetBox container.** `nsc commands --schema bundled-default
-   --output json` produces a deterministic command-model for tests that
-   don't need a live NetBox.
+2. **CI without a NetBox container.** Pointing `--schema` at a bundled
+   snapshot path (e.g. `nsc commands --schema
+   nsc/schemas/bundled/netbox-4.6.0.json.gz --output json`) produces a
+   deterministic command-model for tests that don't need a live NetBox.
+   `--schema` accepts an `http(s)://` URL or a local path; `.json.gz`
+   files are gunzipped automatically — there is no `bundled` keyword.

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/contributing/development.md

@@ -22,7 +22,7 @@ just lint          # ruff + ruff format --check + mypy --strict
 just fix           # auto-fix ruff issues
 just bench         # cold-start benchmark (target <300ms median)
 just nsc <args>    # run the local CLI (e.g., just nsc dcim devices list)
-just docs          # serve the docs site at http://localhost:8000
+just docs          # serve the docs site at http://127.0.0.1:8000
 just docs-build    # build the site, fail on broken links / missing nav
 ```
 

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/contributing/release-process.md

@@ -10,6 +10,12 @@ process assumes. Release prep (CHANGELOG roll + version bumps) happens
 on a `chore/release-X.Y.Z` feature branch, gets PR-merged into `main`,
 and only then is `vX.Y.Z` tagged on the resulting merge commit.
 
+The same `v*` tag push also publishes the documentation site.
+`docs.yml` runs build-only (`mkdocs build --strict`) on docs-touching
+pull requests, but the GitHub Pages **deploy** job only runs on a `v*`
+tag push — the live docs site updates on release, not on merge to
+`main`.
+
 ## Normal release checklist
 
 1. Full unit suite green: `just test`.

netbox_super_cli-1.0.4/docs/getting-started/first-run.md

@@ -0,0 +1,88 @@
+# First run
+
+Two paths to your first command:
+
+1. **Interactive wizard** — `nsc init` prompts for everything.
+2. **Env vars** — `NSC_URL` + `NSC_TOKEN` and you're done; no config file needed.
+
+## Interactive: `nsc init`
+
+```sh
+nsc init
+```
+
+The wizard prompts, in order, for:
+
+- A **profile name** (default `default`; e.g., `prod`, `lab`).
+- The NetBox URL.
+- **Verify SSL certificates?** (default yes).
+- **Token storage** — `plaintext` or `env` (default `plaintext`).
+- Then either an **environment variable name** (if you chose `env` storage — written as
+  an `!env NAME` indirection) or the **token** itself (hidden input, stored verbatim in
+  `~/.nsc/config.yaml`). See [Managing profiles](../guides/managing-profiles.md).
+
+`nsc init` is offline-safe: it does not contact NetBox. On success it writes
+`~/.nsc/config.yaml` with the profile, prints the path, and suggests
+`nsc login --profile <name>` as the next step. It does **not** fetch the
+schema — run `nsc login` afterwards to verify the token and prime the schema
+cache (see below).
+
+`nsc init` refuses to overwrite an existing config — use
+`nsc login --new --profile <name> --url <url>` to add more profiles.
+
+## Env-var only
+
+For one-off use, agents, or CI:
+
+```sh
+export NSC_URL=https://netbox.example.com
+export NSC_TOKEN=$(cat ~/.netbox-token)
+
+nsc dcim devices list
+```
+
+No `~/.nsc/config.yaml` required. The cache lives at `~/.nsc/cache/adhoc/`
+when there's no profile.
+
+## Authenticate / verify a profile
+
+```sh
+nsc login                          # verify the default profile
+nsc login --profile lab            # verify a specific profile
+nsc login --new --profile staging --url https://netbox-staging.example.com
+nsc login --rotate --profile prod  # rotate the token
+nsc login --fetch-schema           # verify, then fetch & cache the live schema
+```
+
+`nsc login` probes `GET /api/status/` and `GET /api/users/tokens/?limit=1`
+(both must succeed) and prints `✓ authenticated as <user>, NetBox <version>`
+on success. On failure it emits the standard auth error envelope
+(`type: auth`, exit 8).
+
+`--new` requires both `--profile` and `--url`, prompts for the token
+(hidden input), verifies it before writing, and persists the profile. After a
+successful `--new` it also asks **"Fetch and cache the live schema now?"**
+(default **yes**) — accepting primes the schema cache so your first real
+command skips the bootstrap fetch. Pass `--fetch-schema` to any `nsc login`
+(or `--new`) to fetch the schema unconditionally without the prompt;
+`--rotate` neither prompts for nor fetches the schema.
+
+## Your first read
+
+```sh
+nsc dcim devices list                       # default page (page_size=50)
+nsc dcim devices list --all                 # paginate to completion
+nsc dcim devices get 7                      # get by id
+nsc ls devices                              # alias — matches devices.list
+nsc dcim devices list --output json --all   # canonical machine-readable form
+```
+
+## Your first write
+
+```sh
+nsc dcim devices create --field name=test-1 --field site=2 --explain  # dry-run + reasoning
+nsc dcim devices create --field name=test-1 --field site=2 --apply    # commit
+nsc rm devices test-1 --apply                                          # delete via alias
+```
+
+Every write previews as a dry-run unless you pass `--apply`. See [Writes and safety](../guides/writes-and-safety.md) for the full discipline.

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/guides/ci-and-automation.md

@@ -89,10 +89,17 @@ just means one extra fetch on the next run — never a wrong command tree.
 
 ```sh
 # Verify connectivity + auth before doing anything mutating.
-nsc login --output json || { echo "auth failed"; exit 1; }
+nsc login || { echo "auth failed"; exit 1; }
 ```
 
+`nsc login` verifies the active profile's token (exit **8** on auth failure,
+**12** on a config/profile problem). It takes no `--output` flag; on failure it
+prints the standard JSON error envelope.
+
 ## Cleaning up the cache
 
-`nsc cache prune` removes orphan profile dirs and stale-hash files (with `--apply`).
-Safe to run unattended; never deletes the `adhoc` cache.
+`nsc cache prune` removes orphan profile dirs and stale-hash files (it is
+dry-run unless you pass `--apply`). The default prune never touches the
+`adhoc` cache. Add `--max-age N` to also prune cache files older than N days
+by mtime — note that age-based pruning is profile-agnostic and *will* remove
+aged `adhoc` files too. Safe to run unattended (dry-run by default).

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/guides/managing-profiles.md

@@ -16,8 +16,8 @@ nsc profiles add lab --url https://netbox-lab.local --token "$LAB_TOKEN"
 ```
 
 This is the scriptable equivalent of `nsc login --new --profile lab`. It runs
-the same verification (`GET /api/users/tokens/?limit=1`) before persisting.
-Refuses if `lab` already exists.
+the same verification (`GET /api/status/` plus `GET /api/users/tokens/?limit=1`)
+before persisting. Refuses if `lab` already exists.
 
 ## Add a profile interactively
 
@@ -26,6 +26,31 @@ nsc init                                                              # first ti
 nsc login --new --profile staging --url https://netbox-staging.local  # subsequent profiles
 ```
 
+`nsc login --new` requires both `--profile` and `--url`, then prompts for the
+token (hidden input) and runs verification before persisting. Add `--store env
+--env-var NAME` to store the token as an `!env NAME` reference instead of
+plaintext. Refuses (exit 12) if the profile already exists.
+
+After a successful `--new`, `nsc` interactively asks **"Fetch and cache the
+live schema now?"** (default **yes**) — accept it to pre-warm the command-model
+cache, or pass `--fetch-schema` to fetch unconditionally without the prompt.
+
+## Verify, rotate, and fetch the schema
+
+```sh
+nsc login                                    # verify the default profile's token
+nsc login --profile lab                      # verify a specific profile
+nsc login --profile lab --fetch-schema       # verify, then refresh the cached schema
+nsc login --rotate --profile lab             # prompt for a new token, verify, then persist
+```
+
+`nsc login` (bare or with `--profile`) verifies the token by probing
+`GET /api/status/` and `GET /api/users/tokens/?limit=1`; it writes no config.
+`--fetch-schema` additionally force-refreshes the cached OpenAPI schema.
+`--rotate` requires `--profile`, prompts for the new token, verifies it
+*before* writing, and does **not** prompt for or fetch the schema. `--new` and
+`--rotate` are mutually exclusive.
+
 ## Rename / set default / remove
 
 ```sh

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/guides/output-formats.md

@@ -1,7 +1,10 @@
 # Output formats
 
-`nsc` ships five output formats. Default is **table** on a TTY and **JSON** when
-stdout is piped.
+`nsc` ships five output formats: `table`, `json`, `jsonl`, `yaml`, `csv`.
+Default is **table** on a TTY and **JSON** when stdout is piped — the piped
+default is JSON even if your config sets a different `defaults.output`.
+Selection precedence (highest first): `--output`/`-o` > `NSC_OUTPUT` env var >
+non-TTY → JSON > `defaults.output` in config (default `table`).
 
 ## The five formats
 

{netbox_super_cli-1.0.3 → netbox_super_cli-1.0.4}/docs/guides/using-with-ai-agents.md

@@ -9,7 +9,7 @@ correctly without trial-and-error.
 | Feature | Mechanism |
 |---|---|
 | Predictable command shape | `nsc <tag> <resource> <verb>` — derived from the OpenAPI schema, no hand-curation |
-| Self-describing | `nsc commands --output json` dumps the full command-model; `nsc describe <tag> <resource>` dumps a resource's fields/filters/operations |
+| Self-describing | `nsc commands --schema <path-or-url> --output json` dumps the full command-model (tags → resources → operations) |
 | Stable machine output | `--output json` everywhere; data on stdout, errors as JSON on stderr (or stdout when `--output json`), non-zero exit on failure |
 | Stable error envelope | `{error, type, endpoint, method, status_code, operation_id, details}` — locked schema, see [Exit codes](../reference/exit-codes.md) |
 | Safe by default | Writes preview as dry-runs; `--apply` is the only path to mutation |
@@ -18,15 +18,26 @@ correctly without trial-and-error.
 ## Bundled portable Skill
 
 `nsc` ships a portable Skill bundle at `skills/netbox-super-cli/SKILL.md`
-(installed inside the wheel). Install it into your agent harness with:
+(installed inside the wheel). Install it into a known agent harness with:
 
 ```sh
 nsc skill install --target claude-code            # dry-run; prints the destination
 nsc skill install --target claude-code --apply    # actually copies
 ```
 
+Or export the bundled `SKILL.md` to an arbitrary directory:
+
+```sh
+nsc skill export ./my-skills                      # dry-run; prints the would-write path
+nsc skill export ./my-skills --apply              # actually copies
+```
+
+`nsc skill export <dir>` always writes to `<dir>/netbox-super-cli/SKILL.md` —
+the `netbox-super-cli/` subdirectory is inserted for you. Both `skill install`
+and `skill export` are **dry-run unless `--apply`** is passed.
+
 Use `--output json` for programmatic consumers; the dry-run envelope contains
-the resolved `destination` path.
+the resolved destination path.
 
 ### Per-target resolved paths
 
@@ -54,9 +65,9 @@ When briefing an agent to use `nsc`, include:
    read command.
 2. **The output format.** "Use `--output json` for everything. Errors are JSON
    envelopes — read `.type` for the category, the exit code for control flow."
-3. **Discovery commands.** "Run `nsc commands --output json` to see the whole
-   surface. Run `nsc describe <tag> <resource>` for a specific resource's
-   fields." This prevents the agent from guessing endpoints.
+3. **Discovery commands.** "Run `nsc commands --schema <path-or-url> --output
+   json` to see the whole surface (tags → resources → operations)." This
+   prevents the agent from guessing endpoints.
 4. **The audit log.** "If a command fails unexpectedly, check
    `~/.nsc/logs/audit.jsonl` — it has the exact request and response." This
    replaces guesswork with evidence.
@@ -66,6 +77,6 @@ When briefing an agent to use `nsc`, include:
 - **Asking the agent to skip dry-run.** Just don't. The dry-run is the agent's
   one chance to surface an objection.
 - **Hand-curated endpoint lists in the prompt.** They go stale on every NetBox
-  upgrade. Use `nsc commands --output json` instead.
+  upgrade. Use `nsc commands --schema <path-or-url> --output json` instead.
 - **Authenticating per-command.** Configure a profile (or env vars) once at
   session start.