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

netbox_super_cli-1.0.2/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

{netbox_super_cli-1.0.0 → netbox_super_cli-1.0.2}/.gitignore

@@ -35,3 +35,6 @@ docs/superpowers/
 
 # mkdocs
 site/
+
+# git worktrees
+.worktrees/

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

@@ -7,7 +7,7 @@
 
 # Working on netbox-super-cli (for AI agents)
 
-This is the contributor guide for AI agents (and humans!) modifying this repo. The end-user-facing AI guide is the bundled Skill at `skills/netbox-super-cli/SKILL.md` (added in Phase 5).
+This is the contributor guide for AI agents (and humans!) modifying this repo. The end-user-facing AI guide is the bundled Skill at `skills/netbox-super-cli/SKILL.md`.
 
 ## Architecture cheat sheet
 
@@ -15,10 +15,13 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `nsc/model/` — the normalized command tree (data only, framework-free). The "brain".
 - `nsc/builder/` — converts a parsed schema into a `CommandModel`.
 - `nsc/cli/` — the Typer app; consumes a `CommandModel`.
-- `nsc/http/` — thin httpx wrapper (Phase 2+).
-- `nsc/output/` — formatters (Phase 2+).
-- `nsc/config/` — config loader + Pydantic models (Phase 1 has a minimal version).
+- `nsc/http/` — thin httpx wrapper: auth, retries, audit log.
+- `nsc/output/` — formatters (table/json/jsonl/yaml/csv) + error envelope.
+- `nsc/config/` — config loader + Pydantic models + ruamel.yaml round-trip writer.
 - `nsc/cache/` — disk cache for generated command-models.
+- `nsc/auth/` — login verification helpers (pre-flight probes, token rotate).
+- `nsc/aliases/` — curated alias resolver (`ls`, `get`, `rm`, `search`). Framework-free.
+- `nsc/skill/` — bundle-path helper for the portable `SKILL.md` shipped in the wheel.
 - `nsc/schemas/bundled/` — versioned NetBox OpenAPI snapshots, fallback when offline.
 
 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 probably solving the wrong problem.
@@ -39,6 +42,14 @@ The hard rule: **`nsc/model/` imports nothing from `nsc/cli/`, `nsc/http/`, or a
 - TDD: write the failing test first.
 - No comments on what code does; only on non-obvious *why*.
 
+## Branching
+
+`main` is protected — direct pushes are rejected. All work happens on
+short-lived feature branches (`fix/<slug>`, `feat/<slug>`, `docs/<slug>`,
+…), opens a PR against `main`, passes required CI checks, and squash-merges.
+Releases are *tags* on `main`, not branches. Full convention:
+[`docs/contributing/branching.md`](docs/contributing/branching.md).
+
 ## Where the design lives
 
 - `docs/superpowers/specs/2026-04-30-netbox-super-cli-design.md` — the full design.

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

@@ -2,7 +2,36 @@
 
 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`.
 
-## Unreleased
+## 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.
+
+### Added
+
+- **Schema TTL fast-path** (issue #34). `nsc` now skips the per-invocation `GET /api/schema/` round-trip when a sidecar-validated cache entry is fresh. Freshness is tracked in `~/.nsc/cache/<profile>/<hash>.meta.json` (an explicit `fetched_at` timestamp), not file mtime — so `touch`, backup-restore, or `cp -p` can't fake freshness, and clocks that jumped forward then back are rejected (>60s skew distrusted).
+- **`nsc --refresh-schema <subcmd>`** — one-shot forced refresh that bypasses the TTL even on `daily`/`weekly`/`manual` policies. Use after a NetBox upgrade to pick up a new schema immediately without changing config.
+- Atomic cache writes — `CacheStore.save` now writes via temp-file + `os.replace`, so a concurrent `nsc` reader can never observe a partial cache file.
+- **`nsc init` prompts for SSL verification** (issue #22). The first-run wizard now asks `Verify SSL certificates?` (defaults `Y`) after URL entry. Accepting the default keeps the config minimal (no `verify_ssl` key written); answering `n` writes `verify_ssl: false` into the profile block.
+
+### Changed
+
+- **Default `defaults.schema_refresh` is now `daily`** (was `on-hash-change`). This is the user-visible behaviour change behind the fast-path: under the new default, `nsc` trusts a cached schema for 24h. **If you need the v1.0.1 behaviour** (re-fetch every invocation to detect a schema change immediately), set `defaults.schema_refresh: on-hash-change` in `~/.nsc/config.yaml`. To force a one-shot refresh under any policy, prepend `--refresh-schema` to the command. Existing configs with an explicit `schema_refresh` value are unaffected.
+- Cache files written before this release have no sidecar and will be treated as stale on first invocation after upgrade — `nsc` refetches once, writes the sidecar, and the fast-path is active from there.
+
+### Documentation
+
+- LICENSE file normalized byte-for-byte to the apache.org canonical Apache 2.0 text (issue #18).
+- Trunk-based branching guide added at `docs/contributing/branching.md`; branch protection enabled on `main` (PR #28).
+- Bundled Skill (`skills/netbox-super-cli/SKILL.md`) gained a NetBox device type library section (PR #27).
+
+## v1.0.1 — 2026-05-06
+
+First patch release. Two bug fixes; no API or behavior changes elsewhere.
+
+### Fixed
+
+- **`nsc commands --schema <https-url>` now honours `--insecure`, `NSC_INSECURE`, and the active profile's `verify_ssl: false`** (issue #8). The `commands` meta-command bypasses the bootstrap pipeline that resolves the SSL flag, so it had been calling `httpx.get` with `verify=True` regardless of the user's configuration. The handler now reads the global state and a new `resolve_transport_settings` helper computes `(verify_ssl, timeout)` without requiring URL/token (which `commands` does not need).
+- **`nsc commands` and `nsc config <…>` now run when `~/.nsc/config.yaml` fails to parse** (issue #10). The `ConfigParseError` recovery branch in `nsc/cli/app.py:_root` listed only 5 of the 7 meta subcommands — `commands` and `config` were missing, so running them against a malformed config aborted with the unhelpful root-level `Error: <ConfigParseError>` instead of recovering to an empty `Config()`. The recovery set is now sourced from `_META_COMMANDS` directly (single source of truth).
 
 ## v1.0.0 — 2026-05-06
 

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

@@ -1,6 +1,6 @@
 # Working on netbox-super-cli (for AI agents)
 
-This is the contributor guide for AI agents (and humans!) modifying this repo. The end-user-facing AI guide is the bundled Skill at `skills/netbox-super-cli/SKILL.md` (added in Phase 5).
+This is the contributor guide for AI agents (and humans!) modifying this repo. The end-user-facing AI guide is the bundled Skill at `skills/netbox-super-cli/SKILL.md`.
 
 ## Architecture cheat sheet
 
@@ -8,10 +8,13 @@ This is the contributor guide for AI agents (and humans!) modifying this repo. T
 - `nsc/model/` — the normalized command tree (data only, framework-free). The "brain".
 - `nsc/builder/` — converts a parsed schema into a `CommandModel`.
 - `nsc/cli/` — the Typer app; consumes a `CommandModel`.
-- `nsc/http/` — thin httpx wrapper (Phase 2+).
-- `nsc/output/` — formatters (Phase 2+).
-- `nsc/config/` — config loader + Pydantic models (Phase 1 has a minimal version).
+- `nsc/http/` — thin httpx wrapper: auth, retries, audit log.
+- `nsc/output/` — formatters (table/json/jsonl/yaml/csv) + error envelope.
+- `nsc/config/` — config loader + Pydantic models + ruamel.yaml round-trip writer.
 - `nsc/cache/` — disk cache for generated command-models.
+- `nsc/auth/` — login verification helpers (pre-flight probes, token rotate).
+- `nsc/aliases/` — curated alias resolver (`ls`, `get`, `rm`, `search`). Framework-free.
+- `nsc/skill/` — bundle-path helper for the portable `SKILL.md` shipped in the wheel.
 - `nsc/schemas/bundled/` — versioned NetBox OpenAPI snapshots, fallback when offline.
 
 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 probably solving the wrong problem.
@@ -32,6 +35,14 @@ The hard rule: **`nsc/model/` imports nothing from `nsc/cli/`, `nsc/http/`, or a
 - TDD: write the failing test first.
 - No comments on what code does; only on non-obvious *why*.
 
+## Branching
+
+`main` is protected — direct pushes are rejected. All work happens on
+short-lived feature branches (`fix/<slug>`, `feat/<slug>`, `docs/<slug>`,
+…), opens a PR against `main`, passes required CI checks, and squash-merges.
+Releases are *tags* on `main`, not branches. Full convention:
+[`docs/contributing/branching.md`](docs/contributing/branching.md).
+
 ## Where the design lives
 
 - `docs/superpowers/specs/2026-04-30-netbox-super-cli-design.md` — the full design.

{netbox_super_cli-1.0.0 → netbox_super_cli-1.0.2}/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -32,10 +33,10 @@
       not limited to compiled object code, generated documentation,
       and conversions to other media types.
 
-      "Work" shall mean the work of authorship, whether in Source or Object
-      form, made available under the License, as indicated by a copyright
-      notice that is included in or attached to the work (an example is
-      provided in the Appendix below).
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -155,7 +156,7 @@
       unless required by applicable law (such as deliberate and grossly
       negligent acts) or agreed to in writing, shall any Contributor be
       liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
+      incidental, or consequential damages of any character arising as a
       result of this License or out of the use or inability to use the
       Work (including but not limited to damages for loss of goodwill,
       work stoppage, computer failure or malfunction, or any and all
@@ -163,12 +164,12 @@
       has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, you may choose to offer,
+      the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
       or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, you may act only
-      on your own behalf and on your sole responsibility, not on behalf
-      of any other Contributor, and only if you agree to indemnify,
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
       defend, and hold each Contributor harmless for any liability
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netbox-super-cli
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -31,8 +31,6 @@ A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dyna
 
 > **Docs:** [thomaschristory.github.io/netbox-super-cli](https://thomaschristory.github.io/netbox-super-cli/) — the full guide, including install, first-run, guides, and the auto-generated CLI/config/exit-code reference.
 
-> **Status:** Phase 3 complete (`v0.3.0-phase3`). The full read + safe-write surface is shipped: dynamic command tree, dry-run-by-default writes with `--apply` to commit, `--explain` for resolved-request introspection, bulk-endpoint detection with loop fallback, stable error envelopes with locked exit codes, append-only audit log, and a live-NetBox e2e suite running in CI against `netboxcommunity/netbox:v4.5.9`. Not yet on PyPI.
-
 ## Why
 
 - **Plugins just work.** If your install has plugins, their endpoints appear as commands automatically.
@@ -40,13 +38,15 @@ A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dyna
 - **Safe by default.** POST/PATCH/PUT/DELETE preview as dry-runs unless you pass `--apply`.
 - **Agent-friendly.** Deterministic command shape, machine-readable JSON output, stable error envelope with documented exit codes.
 
-## Install (preview)
+## Install
 
 ```
 uv tool install netbox-super-cli
+# or, with pipx:
+pipx install netbox-super-cli
 ```
 
-Not on PyPI yet; install from source:
+Or from source:
 ```
 git clone https://github.com/thomaschristory/netbox-super-cli
 cd netbox-super-cli
@@ -114,7 +114,7 @@ Stdin is sniffed from the first 512 bytes (first non-whitespace byte plus a one-
 - HTTP headers in the `SENSITIVE_HEADERS` set (e.g. `Authorization`, `X-API-Key`) — replaced with `"<redacted>"`.
 - Request-body fields whose OpenAPI definition has `format: password` OR whose name (case-insensitive) is one of: `password`, `secret`, `token`, `api_key`, `apikey`, `private_key`, `passphrase`, `client_secret`. Nested fields and arrays of objects are walked recursively.
 
-The wire body sent to NetBox is **not** redacted — only the audit log. A failed write still records the redacted body; redaction is irreversible. Treat `audit.jsonl` like a verbose application log: gate it behind your home-directory permissions and rotate / archive accordingly. A "redact everything" mode is deferred to Phase 5+.
+The wire body sent to NetBox is **not** redacted — only the audit log. A failed write still records the redacted body; redaction is irreversible. Treat `audit.jsonl` like a verbose application log: gate it behind your home-directory permissions and rotate / archive accordingly. A "redact everything" mode is on the post-v1.0 roadmap.
 
 ## Output and errors
 

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

@@ -4,8 +4,6 @@ A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dyna
 
 > **Docs:** [thomaschristory.github.io/netbox-super-cli](https://thomaschristory.github.io/netbox-super-cli/) — the full guide, including install, first-run, guides, and the auto-generated CLI/config/exit-code reference.
 
-> **Status:** Phase 3 complete (`v0.3.0-phase3`). The full read + safe-write surface is shipped: dynamic command tree, dry-run-by-default writes with `--apply` to commit, `--explain` for resolved-request introspection, bulk-endpoint detection with loop fallback, stable error envelopes with locked exit codes, append-only audit log, and a live-NetBox e2e suite running in CI against `netboxcommunity/netbox:v4.5.9`. Not yet on PyPI.
-
 ## Why
 
 - **Plugins just work.** If your install has plugins, their endpoints appear as commands automatically.
@@ -13,13 +11,15 @@ A Python CLI for [NetBox](https://netbox.dev/) that builds its command tree dyna
 - **Safe by default.** POST/PATCH/PUT/DELETE preview as dry-runs unless you pass `--apply`.
 - **Agent-friendly.** Deterministic command shape, machine-readable JSON output, stable error envelope with documented exit codes.
 
-## Install (preview)
+## Install
 
 ```
 uv tool install netbox-super-cli
+# or, with pipx:
+pipx install netbox-super-cli
 ```
 
-Not on PyPI yet; install from source:
+Or from source:
 ```
 git clone https://github.com/thomaschristory/netbox-super-cli
 cd netbox-super-cli
@@ -87,7 +87,7 @@ Stdin is sniffed from the first 512 bytes (first non-whitespace byte plus a one-
 - HTTP headers in the `SENSITIVE_HEADERS` set (e.g. `Authorization`, `X-API-Key`) — replaced with `"<redacted>"`.
 - Request-body fields whose OpenAPI definition has `format: password` OR whose name (case-insensitive) is one of: `password`, `secret`, `token`, `api_key`, `apikey`, `private_key`, `passphrase`, `client_secret`. Nested fields and arrays of objects are walked recursively.
 
-The wire body sent to NetBox is **not** redacted — only the audit log. A failed write still records the redacted body; redaction is irreversible. Treat `audit.jsonl` like a verbose application log: gate it behind your home-directory permissions and rotate / archive accordingly. A "redact everything" mode is deferred to Phase 5+.
+The wire body sent to NetBox is **not** redacted — only the audit log. A failed write still records the redacted body; redaction is irreversible. Treat `audit.jsonl` like a verbose application log: gate it behind your home-directory permissions and rotate / archive accordingly. A "redact everything" mode is on the post-v1.0 roadmap.
 
 ## Output and errors
 

{netbox_super_cli-1.0.0 → netbox_super_cli-1.0.2}/docs/architecture/caching.md

@@ -26,7 +26,7 @@ one-line "schema changed, regenerating…" notice on stderr.
 
 ## Cleaning up
 
-`nsc cache prune` (Phase 5a) handles three classes of orphan:
+`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

netbox_super_cli-1.0.2/docs/architecture/schema-loading.md

@@ -0,0 +1,84 @@
+# Schema loading
+
+`nsc/schema/` fetches and parses the OpenAPI document.
+
+## Resolution order
+
+Highest priority first, given the active `defaults.schema_refresh` policy
+and an optional `--refresh-schema` override:
+
+1. `--schema <path-or-url>` — one-shot override. Always wins; never
+   consults the TTL fast-path or the network.
+2. **TTL fast-path.** If the policy is `daily`, `weekly`, or `manual` and
+   the newest sidecar-validated cache entry for the active profile is
+   fresher than the policy's TTL, `nsc` returns it directly with no HTTP
+   round-trip. Skipped when `--refresh-schema` is passed (or the policy
+   is `on-hash-change`).
+3. Live fetch from the active profile's `schema_url` (explicit) or
+   `{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.
+
+## Hashing
+
+The cache key is `sha256` of the canonicalized schema body (JSON
+re-serialized with sorted keys, no whitespace). Cosmetic changes to the
+upstream schema (whitespace, key order) don't bust the cache, but any
+semantic change (new endpoint, changed field) does.
+
+## Cache layout
+
+Each profile has a directory under `~/.nsc/cache/<profile>/` containing,
+per schema hash:
+
+- `<hash>.json` — the generated `CommandModel`. Loaded via
+  `CacheStore.load`, which re-verifies that the file's embedded
+  `schema_hash` matches the filename — so a tampered or copied JSON
+  file is rejected.
+- `<hash>.meta.json` — a sidecar with `{"fetched_at": <epoch_seconds>}`.
+  Drives the TTL fast-path. Written atomically alongside the cache file
+  via temp-file + `os.replace`.
+
+A sidecar dated more than 60s in the future (clock skew or tampering)
+is rejected. A cache entry without its sidecar is treated as stale —
+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.
+
+## Refresh modes
+
+In `~/.nsc/config.yaml`:
+
+```yaml
+defaults:
+  schema_refresh: daily   # default since the v1.0.2 release line
+```
+
+| Value            | TTL    | Behaviour                                                       |
+|------------------|--------|-----------------------------------------------------------------|
+| `daily`          | 24h    | Default. Trust a fresh cache; re-fetch once a day.              |
+| `weekly`         | 7d     | Trust longer; suitable for stable NetBox deployments.           |
+| `manual`         | ∞      | Never auto-invalidate. Use `--refresh-schema` to update.        |
+| `on-hash-change` | 0      | v1.0.1 behaviour: re-fetch every invocation, compare hashes.    |
+
+Use `nsc --refresh-schema <subcommand>` to force a one-shot refresh
+that bypasses the TTL fast-path under any policy.
+
+## When you change NetBox versions
+
+The hash changes → next invocation that bypasses the fast-path
+regenerates the model. Under `daily` (the default) you may need to
+prepend `--refresh-schema` to your first post-upgrade invocation, or
+wait up to 24h. The old `<old_hash>.json` (and its sidecar) become
+orphaned and get cleaned by `nsc cache prune`.

netbox_super_cli-1.0.2/docs/contributing/branching.md

@@ -0,0 +1,110 @@
+# Branching and merging
+
+`netbox-super-cli` follows trunk-based development with short-lived
+feature branches. There is exactly one long-lived branch — `main` —
+and it is always releasable.
+
+## The branches
+
+- **`main`** — the integration branch. Every accepted change lands here.
+  Each commit on `main` is a candidate for the next release.
+- **Feature branches** — short-lived, named for the change they carry.
+  Created from `main`, deleted on merge.
+- **Tags** (`vX.Y.Z`) — the release artifact. A tag points at a commit
+  on `main`; `release.yml` builds and publishes from the tagged commit.
+
+There is no separate "release branch". A release is a *tagged commit
+on `main`*, not a branch. Multiple unreleased commits accumulate on
+`main` between tags; tagging snapshots them into a release.
+
+## Naming convention
+
+Feature branches use a `<type>/<short-slug>` prefix matching the
+[Conventional Commit](https://www.conventionalcommits.org/) types:
+
+- `feat/<slug>` — new feature.
+- `fix/<slug>` — bug fix.
+- `docs/<slug>` — documentation only.
+- `refactor/<slug>` — internal restructure, no behaviour change.
+- `chore/<slug>` — tooling, dependency bumps, release prep.
+- `ci/<slug>` — workflow / CI changes.
+- `test/<slug>` — test-only changes.
+
+Agent-generated branches may use the existing `claude/issue-<n>-<date>`
+pattern; the prefix isn't load-bearing as long as the branch is
+short-lived.
+
+## Lifecycle of a change
+
+1. Branch from latest `main`:
+   ```sh
+   git checkout main && git pull
+   git checkout -b fix/<slug>
+   ```
+2. Commit using Conventional Commits (`fix(scope): subject`).
+3. Push and open a PR against `main`. CI runs.
+4. Once green and (if applicable) reviewed, **squash-merge** to `main`.
+   Squashing keeps `main` one-commit-per-PR — easy to scan, easy to
+   revert.
+5. Delete the feature branch (`gh pr merge --delete-branch`, or the
+   "Delete branch" button on the PR).
+
+The squashed commit subject follows `<type>(scope): subject (#N)` —
+matching the existing convention seen on PRs #8, #10, #26.
+
+## Branch protection on `main`
+
+`main` is protected. The exact rules are configured via the GitHub
+branch-protection API; the current policy is:
+
+- **No direct pushes.** Every change goes through a pull request.
+- **Required status checks** must pass before merge:
+  - `lint`
+  - `test (ubuntu-latest, 3.12)`
+- **Force pushes blocked.**
+- **Branch deletion blocked.**
+- **Administrators are not exempt.** Even repo owners go through PRs.
+
+To inspect or change the rule:
+
+```sh
+gh api repos/:owner/:repo/branches/main/protection
+gh api repos/:owner/:repo/branches/main/protection -X PUT --input rules.json
+```
+
+If a status-check job is renamed in CI, update `contexts` in the
+protection rule the same day — otherwise PRs will hang waiting for a
+check that no longer runs.
+
+## Releases vs. branches
+
+Releases are a *separate* concern from branching:
+
+- Release prep (CHANGELOG roll, version bumps in `pyproject.toml` and
+  `nsc/_version.py`) happens on a `chore/release-X.Y.Z` branch.
+- Open a PR for the release prep, merge to `main`, **then** tag the
+  resulting merge commit:
+  ```sh
+  git checkout main && git pull
+  git tag -a vX.Y.Z -m "vX.Y.Z"
+  git push origin vX.Y.Z
+  ```
+- The tag triggers `release.yml`, which builds the wheel + sdist and
+  publishes to PyPI.
+- See [`release-process.md`](release-process.md) for the full checklist.
+
+We do **not** maintain release branches (`release/v1.x`) at this time.
+Milestones (e.g. `v1.0.2`, `v1.1.0`) track *what's planned* for which
+release without forking the codebase.
+
+## Why no long-lived release branches?
+
+For a single-trunk project, release branches add merge overhead
+(every fix needs two homes) without benefit. A milestone tells us
+"this issue is scoped to v1.0.2"; the actual code change lives on
+`main` and ships when we tag.
+
+The day we need to support v1.x and v2.x simultaneously, we'll cut
+`release/v1.x` from the last v1.* tag and start cherry-picking
+qualifying fixes into it. Until then, `main` is the only place code
+lives.

netbox_super_cli-1.0.2/docs/contributing/release-process.md

@@ -0,0 +1,94 @@
+# Release process
+
+`nsc` follows [Semantic Versioning](https://semver.org/) from v1.0.0 onward.
+Releases are tag-driven: `release.yml` fires on `v*.*.*` tag pushes and
+publishes to PyPI via trusted publishing (no API tokens).
+
+A release is a **tagged commit on `main`**, not a separate branch — see
+[Branching and merging](branching.md) for the trunk-based workflow this
+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.
+
+## Normal release checklist
+
+1. Full unit suite green: `just test`.
+2. Lint clean: `just lint`.
+3. Bench median <300 ms: `just bench`.
+4. E2E green (requires Docker): `just e2e`.
+5. Roll `CHANGELOG.md`: move `[Unreleased]` to `[vX.Y.Z] — YYYY-MM-DD`.
+6. Bump `pyproject.toml` `[project].version` and `nsc/_version.py` `__version__`
+   to match the tag.
+7. Verify all issues attached to the matching
+   [GitHub milestone](https://github.com/thomaschristory/netbox-super-cli/milestones)
+   are resolved or deferred (don't close the milestone yet — that happens
+   after publish, see below).
+8. Commit: `git commit -m "chore(release): X.Y.Z"`.
+9. Annotate and push: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z`.
+10. Watch `release.yml` publish the wheel and create the GitHub Release.
+11. Once PyPI shows the new version and the GitHub Release is live, close
+    the milestone and open the next one — see the next section for the
+    exact `gh api` invocations.
+
+## GitHub milestones convention
+
+Each planned release has a milestone named after its version (e.g., `v1.1.0`).
+Issues and PRs are triaged to a milestone when they are scoped to a specific
+release. Milestones don't gate CI — they're a planning aid that surfaces
+what's queued for which version.
+
+- Milestone name: `vX.Y.Z` (matches the git tag exactly).
+- An open milestone with no due date means "planned but not scheduled".
+- The `main` branch is always releasable; milestones don't block merges.
+
+**Once a release is published**, close its milestone and open the next one.
+This is step 11 of the release checklist; the exact commands are:
+
+1. Bump or close any open issues left in the just-shipped milestone —
+   either move them to the next milestone or drop them to the backlog.
+2. Close the milestone:
+   ```sh
+   gh api repos/:owner/:repo/milestones/<N> -X PATCH -f state=closed
+   ```
+3. Open the next one:
+   ```sh
+   gh api repos/:owner/:repo/milestones -f title='v<next>' -f state=open
+   ```
+   For a patch release, increment the patch number; for a minor/major,
+   pick whatever's next based on what's queued.
+4. Leave the new milestone otherwise empty — issues get attached as they're
+   triaged.
+
+This keeps a milestone always available to file new issues against without
+having to think about it mid-bug-report.
+
+## Patch releases (bug fixes)
+
+Patch bumps (`Z` increment) follow the same checklist. Because they contain
+only bug fixes, the E2E run can be skipped if the fix is confined to a code
+path not exercised by the E2E suite — but running it is still recommended.
+
+## Minor / major releases
+
+Minor (`Y`) or major (`X`) bumps follow the full checklist. Before tagging,
+open a tracking issue or milestone for any follow-on items deferred from the
+release.
+
+## Hot-fixing a tagged release
+
+Never amend a tagged commit. Increment the patch component (e.g.,
+`v1.0.1` → `v1.0.2`), cut a fresh patch release with the fix, and document
+it in `CHANGELOG.md` under a new `[vX.Y.Z]` entry for the new version.
+
+## Versioning policy
+
+From v1.0.0 onward:
+
+- `PATCH` — backwards-compatible bug fixes.
+- `MINOR` — new backwards-compatible features or CLI commands.
+- `MAJOR` — breaking changes to the error envelope, exit codes, or config schema.
+
+The version in `pyproject.toml`, `nsc/_version.py`, and the git tag must
+always agree. `release.yml` validates the tag against `nsc/_version.py`
+before publishing; `pyproject.toml` is not currently checked, so keep it
+in sync manually as part of the release commit.

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

@@ -15,8 +15,6 @@ pipx install netbox-super-cli
 uv tool install netbox-super-cli
 ```
 
-> **Phase 5b note:** the PyPI release lands in Phase 5d. Until then, install from source (see below).
-
 Verify the install:
 
 ```sh

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

@@ -4,8 +4,6 @@ Dynamic NetBox CLI driven by the live OpenAPI schema. The same `nsc` binary work
 against any NetBox version (4.4+) and exposes plugin-provided endpoints automatically
 because the schema — not hand-written code — defines the surface.
 
-> **Status:** Phase 5b. v1.0.0 publish lands in 5d. Until then, install from source.
-
 ## Why nsc
 
 - **Plugins just work.** New endpoints from any installed plugin appear as commands automatically.

{netbox_super_cli-1.0.0 → netbox_super_cli-1.0.2}/docs/reference/config.md

@@ -11,7 +11,7 @@ All fields below describe `~/.nsc/config.yaml`.
 |---|---|---|
 | `default_profile` | `str | None` | `None` |
 | `profiles` | `dict[str, Profile]` | `{}` |
-| `defaults` | `<class 'Defaults'>` | `Defaults(output=<OutputFormat.TABLE: 'table'>, page_size=50, timeout=30.0, schema_refresh=<SchemaRefresh.ON_HASH_CHANGE: 'on-hash-change'>)` |
+| `defaults` | `<class 'Defaults'>` | `Defaults(output=<OutputFormat.TABLE: 'table'>, page_size=50, timeout=30.0, schema_refresh=<SchemaRefresh.DAILY: 'daily'>)` |
 | `columns` | `dict[str, dict[str, list[str]]]` | `{}` |
 
 ## `Profile`
@@ -32,4 +32,4 @@ All fields below describe `~/.nsc/config.yaml`.
 | `output` | `<enum 'OutputFormat'>` | `<OutputFormat.TABLE: 'table'>` |
 | `page_size` | `<class 'int'>` | `50` |
 | `timeout` | `<class 'float'>` | `30.0` |
-| `schema_refresh` | `<enum 'SchemaRefresh'>` | `<SchemaRefresh.ON_HASH_CHANGE: 'on-hash-change'>` |
+| `schema_refresh` | `<enum 'SchemaRefresh'>` | `<SchemaRefresh.DAILY: 'daily'>` |

{netbox_super_cli-1.0.0 → netbox_super_cli-1.0.2}/mkdocs.yml

@@ -75,5 +75,6 @@ nav:
       - Caching: architecture/caching.md
   - Contributing:
       - Development: contributing/development.md
+      - Branching and merging: contributing/branching.md
       - Release process: contributing/release-process.md
       - Adding bundled schemas: contributing/adding-bundled-schemas.md