panorama-super-cli 0.1.0__tar.gz

panorama_super_cli-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in the repo.
+*       @thomaschristory

panorama_super_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Something `psc` did wrong
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What you ran and what `psc` did vs. what you expected.
+      placeholder: |
+        $ psc -c export.xml dedup merge --keep a --remove b
+        ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: psc version
+      description: Output of `psc --version`.
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Source
+      options:
+        - Offline (--config file.xml)
+        - Live (--profile)
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Python version, install method (uv/pipx/pip).
+  - type: checkboxes
+    id: sanitized
+    attributes:
+      label: Confirmation
+      options:
+        - label: I have removed any real IPs, hostnames, API keys, or other sensitive config from this report.
+          required: true

panorama_super_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: A new subtool, flag, or capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What object-management problem are you trying to solve?
+      placeholder: "I want to find every object referenced only by disabled rules so I can clean them up."
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed command / behaviour
+      placeholder: "psc refs unused --only-disabled-rules"
+  - type: dropdown
+    id: module
+    attributes:
+      label: Which area?
+      options:
+        - find / resolve
+        - dedup / merge
+        - refs / audit
+        - naming
+        - output / formats
+        - live / API
+        - other

panorama_super_cli-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!-- Conventional Commit title, e.g. feat(dedup): merge service objects -->
+
+## What & why
+
+<!-- What does this change and why? Link the issue: Closes #N -->
+
+## Safety
+
+<!-- For any change to writes/merge/rename/apply: -->
+- [ ] Dry-run remains the default; writes still require `--apply`.
+- [ ] References are repointed before deletes/renames.
+- [ ] Unsafe cases add a `blocker` rather than doing something surprising.
+
+## Checklist
+
+- [ ] `just test` green
+- [ ] `just lint` clean (ruff + mypy --strict)
+- [ ] Tests added for safety-critical paths
+- [ ] Docs / CHANGELOG updated if user-facing
+- [ ] `just sync-agents` run if `CLAUDE.md` changed

panorama_super_cli-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-deps:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

panorama_super_cli-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: docs
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps (runtime + docs)
+        run: uv sync --frozen --group docs
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        if: github.ref_type == 'tag'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

panorama_super_cli-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,41 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Ruff check
+        run: uv run ruff check psc tests
+      - name: Ruff format
+        run: uv run ruff format --check psc tests
+      - name: Mypy strict
+        run: uv run mypy --strict psc
+
+  agents-md-fresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Check AGENTS.md is in sync with CLAUDE.md
+        run: uv run python scripts/sync_agents_md.py --check

panorama_super_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: release
+
+# Tag-only trigger. NEVER on pull_request or branch push — the trusted
+# publisher is bound to this workflow filename + the v* tag pattern.
+on:
+  push:
+    tags:
+      - "v[0-9]*.[0-9]*.[0-9]*"
+
+# Trusted publishing requires id-token: write so the OIDC token issued to
+# pypa/gh-action-pypi-publish is signed.
+permissions:
+  contents: write   # gh release create
+  id-token: write   # PyPI trusted publishing OIDC
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # No `environment:` block — adding one changes the OIDC subject claim and
+    # would break a trusted-publisher binding registered against the
+    # no-environment form.
+    steps:
+      - name: Checkout (full history for changelog notes)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is on main
+        run: |
+          set -euo pipefail
+          git fetch origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "Tag $GITHUB_REF_NAME points at $GITHUB_SHA which is not reachable from main." >&2
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME ($GITHUB_SHA) is on main."
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Sync runtime deps (so the next step can import psc._version)
+        run: uv sync --frozen
+
+      - name: Verify tag matches package version
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(uv run python -c 'from psc._version import __version__; print(__version__)')"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "Tag $GITHUB_REF_NAME -> $tag_version does not match psc/_version.py $pkg_version" >&2
+            exit 1
+          fi
+          echo "Tag $GITHUB_REF_NAME matches package version $pkg_version"
+
+      - name: Build sdist + wheel
+        run: |
+          rm -rf dist
+          uv build --out-dir dist
+          ls -la dist/
+
+      - name: Verify wheel + sdist filenames match tag
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          if ! ls "dist/panorama_super_cli-${tag_version}-py3-none-any.whl" >/dev/null 2>&1; then
+            echo "Wheel for ${tag_version} not found in dist/" >&2; ls dist/ >&2; exit 1
+          fi
+          if ! ls "dist/panorama_super_cli-${tag_version}.tar.gz" >/dev/null 2>&1; then
+            echo "Sdist for ${tag_version} not found in dist/" >&2; ls dist/ >&2; exit 1
+          fi
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          verbose: true
+          skip-existing: true
+
+      - name: Extract changelog section for release notes
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          awk -v ver="$tag_version" '
+            $0 ~ "^## v" ver " " { capture=1; print; next }
+            capture && /^## / { exit }
+            capture { print }
+          ' CHANGELOG.md > /tmp/release-notes.md
+          if [ ! -s /tmp/release-notes.md ]; then
+            echo "Release notes for v${tag_version} not found in CHANGELOG.md" >&2
+            exit 1
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          tag_version="${GITHUB_REF_NAME#v}"
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file /tmp/release-notes.md \
+            "dist/panorama_super_cli-${tag_version}-py3-none-any.whl" \
+            "dist/panorama_super_cli-${tag_version}.tar.gz"

panorama_super_cli-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install ${{ matrix.python }}
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Run tests
+        run: uv run pytest -v

panorama_super_cli-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# venv / uv
+.venv/
+.python-version.local
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# mkdocs
+site/
+
+# editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# local scratch
+/scratch/
+*.local.*
+
+# never commit real Panorama exports or secrets
+*.panrc
+secrets.*
+*.config.xml
+!tests/**/*.xml

panorama_super_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.2
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.7
+          - typer>=0.12
+          - rich>=13.7
+          - "ruamel.yaml>=0.18"
+          - structlog>=24.1
+          - platformdirs>=4.2
+          - types-PyYAML>=6.0
+        args: [--strict]
+        files: ^(psc|scripts)/

panorama_super_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

panorama_super_cli-0.1.0/AGENTS.md

@@ -0,0 +1,97 @@
+<!--
+  AGENTS.md is auto-generated from CLAUDE.md by scripts/sync_agents_md.py.
+  Do NOT edit this file directly — edit CLAUDE.md and run
+  `uv run python scripts/sync_agents_md.py` to regenerate. CI fails the PR
+  if this file drifts from CLAUDE.md (see .github/workflows/lint.yml).
+-->
+
+# Working on panorama-super-cli (for AI agents)
+
+Contributor guide for AI agents (and humans) modifying this repo. The
+*end-user* agent guide is the bundled Skill at
+`skills/panorama-super-cli/SKILL.md` — that one is about *using* `psc`; this one
+is about *changing* it.
+
+## Architecture cheat sheet
+
+The hard split is **backend (`psc/core`) vs frontend (`psc/cli`)**. A future web
+UI would import `psc.core` directly and never touch `psc.cli`.
+
+- `psc/core/models.py` — framework-free Pydantic domain model (`Address`,
+  `AddressGroup`, `Service`, `ServiceGroup`, `Tag`, `SecurityRule`, `NatRule`,
+  `Snapshot`, `Location`). The lingua franca; imports nothing from the rest.
+- `psc/core/parse.py` — Panorama config XML → `Snapshot` (via `defusedxml`).
+- `psc/core/normalize.py` — IP/value canonicalization + matching (the numeric
+  heart of `find` and `dedup`).
+- `psc/core/refs.py` — the reference graph: where-used, unused (recursive),
+  dangling. Models PAN-OS name resolution (DG-local shadows shared).
+- `psc/core/resolve.py` — `find` engine (IP/value/name → objects).
+- `psc/core/dedup.py` — duplicate detection + safe merge planning.
+- `psc/core/naming.py` — opt-in naming templates + reference-aware rename.
+- `psc/core/changeset.py` — the inspectable mutation plan every write produces.
+- `psc/core/setcmd.py` — render objects/changesets as PAN-OS `set` commands.
+- `psc/core/apply_xml.py` — apply a `ChangeSet` to config XML (offline `--apply`).
+- `psc/core/source.py` — `OfflineSource` (file) / `LiveSource` (pan-os-python).
+- `psc/output/` — formatters (table/json/jsonl/yaml/csv/set) + error envelope.
+- `psc/config/` — profiles + defaults (ruamel round-trip).
+- `psc/cli/` — the Typer app; one thin command module per feature group.
+
+The hard rule: **`psc/core/` imports nothing from `psc/cli/` or any UI
+framework.** Engines return models; the CLI formats them. If you reach for
+`typer`/`rich` inside `core/`, you're in the wrong layer.
+
+Features are deliberately independent: `find_cmds`, `dedup_cmds`, `refs_cmds`,
+`name_cmds` each map to one `core` engine and can be deleted without touching
+the others. Reuse lives in `core` (models, refs, changeset, setcmd).
+
+## Common commands
+
+- `just sync` — install/refresh deps.
+- `just test` — run all tests.
+- `just lint` — ruff + mypy --strict.
+- `just fix` — auto-fix ruff issues.
+- `just psc <args>` — run the local CLI.
+- `just sync-agents` — regenerate AGENTS.md from CLAUDE.md.
+
+## Conventions
+
+- Python 3.12+, full type annotations, `mypy --strict`.
+- Pydantic v2 for all structured data.
+- Conventional Commits; squash-merge; `main` is always releasable.
+- TDD: write the failing test first. The safety-critical paths (merge
+  repointing, blockers, apply round-trip, shadow-rename refusal) MUST have tests.
+- Comments explain non-obvious *why*, never *what*.
+
+## Safety model (do not regress)
+
+- **Dry-run is the default.** Mutating commands print a plan and exit without
+  writing unless `--apply` is passed.
+- **Repoint before delete.** A merge/rename rewrites every referencing group,
+  security rule, and NAT rule *before* removing the object.
+- **`ChangeSet.blockers` is a hard gate.** A non-empty `blockers` list means the
+  executor refuses to apply, even with `--apply`. Add a blocker rather than
+  silently doing something surprising (e.g. a cross-scope reference that can't
+  be repointed, or a shared-rename that would shadow a device-group object).
+- **Offline `--apply` never overwrites the source export** — it writes to `--out`.
+
+## Error contract
+
+Expected failures raise `PscError(message, ErrorType.…)`. Exit codes are part
+of the public contract (`psc/output/errors.py::EXIT_CODES`) — don't renumber
+without a major bump. Machine output is never rich-wrapped (`soft_wrap=True`).
+
+## Branching
+
+`main` is protected; work on short-lived `feat/…`, `fix/…`, `docs/…` branches,
+open a PR, get CI (`lint`, `test`) green, squash-merge. Releases are `vX.Y.Z`
+*tags* on `main` (never branches); the tag triggers `release.yml` →
+PyPI (trusted publishing) + the docs site.
+
+Keep `psc/_version.py` and `pyproject.toml` `version` in agreement; the release
+workflow validates the tag against `psc/_version.py`.
+
+## Coordinating work on issues and PRs
+
+When you start on an issue or PR, comment so other agents see it's claimed
+(`gh issue comment <n> -b "…"`). Post terse updates on claim, milestones
+(branch pushed, PR opened, CI green), blockers, and completion.

panorama_super_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `panorama-super-cli` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/), and from v1.0.0 the
+project will follow [Semantic Versioning](https://semver.org/). While on
+`0.x`, minor versions may include breaking changes.
+
+## [Unreleased]
+
+## v0.1.0 — 2026-06-03
+
+First public release. Agent-friendly Panorama object management, offline or live.
+
+### Added
+
+- **Offline + live sources.** Read an exported config with `--config file.xml`,
+  or a live Panorama via a profile (`psc profile add`). The same XML parser
+  feeds both paths.
+- **`psc find ip`** — resolve an IP / CIDR / range / FQDN (or a `--file` list)
+  to the address objects that match it: exact, containing (broader), and
+  within (narrower), plus the address-groups that carry them.
+- **`psc find object`** — locate any object by exact name across all kinds and
+  locations.
+- **`psc dedup addresses|services`** — find objects that share an identical
+  value under different names (e.g. `10.0.0.10` as `h-web1` *and* `web-primary`).
+- **`psc dedup merge`** — collapse one object into another, repointing every
+  group/security-rule/NAT reference *before* deleting it. Refuses (blocks)
+  value-mismatch merges and references that can't be safely repointed.
+- **`psc refs used|unused|dangling`** — where-used pre-flight, recursive unused
+  detection (objects no rule reaches even through groups), and dangling-reference
+  audit.
+- **`psc name lint|rename|apply`** — opt-in naming templates; report drift and
+  perform reference-aware renames that refuse the shared-vs-device-group shadow
+  collision.
+- **Safety model.** Dry-run by default; `--apply` is the only path to a write.
+  Offline `--apply --out fixed.xml` produces a loadable, cleaned config without
+  touching the source export. `ChangeSet.blockers` is a hard refusal gate.
+- **Output formats** `table, json, jsonl, yaml, csv, set` with a stable JSON
+  error envelope and typed exit codes; non-TTY stdout auto-switches to JSON.
+  `-o set` emits ready-to-paste PAN-OS `set` commands (member edits render as
+  delete-then-set, so they're idempotent rather than additive).
+- **Agent Skill** bundled at `skills/panorama-super-cli/SKILL.md`.
+
+### Known limitations (tracked for v0.2)
+
+- Live `--apply` is not yet implemented; use `-o set` or offline `--apply`.
+- Where-used covers address-groups, security rules, and NAT (match +
+  translation). PBF, decryption, authentication, QoS, and other rulebases are
+  not yet scanned.
+- Nested device-group hierarchies are flattened to the leaf; only
+  device-group-shadows-shared inheritance is modelled.

panorama_super_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,90 @@
+# Working on panorama-super-cli (for AI agents)
+
+Contributor guide for AI agents (and humans) modifying this repo. The
+*end-user* agent guide is the bundled Skill at
+`skills/panorama-super-cli/SKILL.md` — that one is about *using* `psc`; this one
+is about *changing* it.
+
+## Architecture cheat sheet
+
+The hard split is **backend (`psc/core`) vs frontend (`psc/cli`)**. A future web
+UI would import `psc.core` directly and never touch `psc.cli`.
+
+- `psc/core/models.py` — framework-free Pydantic domain model (`Address`,
+  `AddressGroup`, `Service`, `ServiceGroup`, `Tag`, `SecurityRule`, `NatRule`,
+  `Snapshot`, `Location`). The lingua franca; imports nothing from the rest.
+- `psc/core/parse.py` — Panorama config XML → `Snapshot` (via `defusedxml`).
+- `psc/core/normalize.py` — IP/value canonicalization + matching (the numeric
+  heart of `find` and `dedup`).
+- `psc/core/refs.py` — the reference graph: where-used, unused (recursive),
+  dangling. Models PAN-OS name resolution (DG-local shadows shared).
+- `psc/core/resolve.py` — `find` engine (IP/value/name → objects).
+- `psc/core/dedup.py` — duplicate detection + safe merge planning.
+- `psc/core/naming.py` — opt-in naming templates + reference-aware rename.
+- `psc/core/changeset.py` — the inspectable mutation plan every write produces.
+- `psc/core/setcmd.py` — render objects/changesets as PAN-OS `set` commands.
+- `psc/core/apply_xml.py` — apply a `ChangeSet` to config XML (offline `--apply`).
+- `psc/core/source.py` — `OfflineSource` (file) / `LiveSource` (pan-os-python).
+- `psc/output/` — formatters (table/json/jsonl/yaml/csv/set) + error envelope.
+- `psc/config/` — profiles + defaults (ruamel round-trip).
+- `psc/cli/` — the Typer app; one thin command module per feature group.
+
+The hard rule: **`psc/core/` imports nothing from `psc/cli/` or any UI
+framework.** Engines return models; the CLI formats them. If you reach for
+`typer`/`rich` inside `core/`, you're in the wrong layer.
+
+Features are deliberately independent: `find_cmds`, `dedup_cmds`, `refs_cmds`,
+`name_cmds` each map to one `core` engine and can be deleted without touching
+the others. Reuse lives in `core` (models, refs, changeset, setcmd).
+
+## Common commands
+
+- `just sync` — install/refresh deps.
+- `just test` — run all tests.
+- `just lint` — ruff + mypy --strict.
+- `just fix` — auto-fix ruff issues.
+- `just psc <args>` — run the local CLI.
+- `just sync-agents` — regenerate AGENTS.md from CLAUDE.md.
+
+## Conventions
+
+- Python 3.12+, full type annotations, `mypy --strict`.
+- Pydantic v2 for all structured data.
+- Conventional Commits; squash-merge; `main` is always releasable.
+- TDD: write the failing test first. The safety-critical paths (merge
+  repointing, blockers, apply round-trip, shadow-rename refusal) MUST have tests.
+- Comments explain non-obvious *why*, never *what*.
+
+## Safety model (do not regress)
+
+- **Dry-run is the default.** Mutating commands print a plan and exit without
+  writing unless `--apply` is passed.
+- **Repoint before delete.** A merge/rename rewrites every referencing group,
+  security rule, and NAT rule *before* removing the object.
+- **`ChangeSet.blockers` is a hard gate.** A non-empty `blockers` list means the
+  executor refuses to apply, even with `--apply`. Add a blocker rather than
+  silently doing something surprising (e.g. a cross-scope reference that can't
+  be repointed, or a shared-rename that would shadow a device-group object).
+- **Offline `--apply` never overwrites the source export** — it writes to `--out`.
+
+## Error contract
+
+Expected failures raise `PscError(message, ErrorType.…)`. Exit codes are part
+of the public contract (`psc/output/errors.py::EXIT_CODES`) — don't renumber
+without a major bump. Machine output is never rich-wrapped (`soft_wrap=True`).
+
+## Branching
+
+`main` is protected; work on short-lived `feat/…`, `fix/…`, `docs/…` branches,
+open a PR, get CI (`lint`, `test`) green, squash-merge. Releases are `vX.Y.Z`
+*tags* on `main` (never branches); the tag triggers `release.yml` →
+PyPI (trusted publishing) + the docs site.
+
+Keep `psc/_version.py` and `pyproject.toml` `version` in agreement; the release
+workflow validates the tag against `psc/_version.py`.
+
+## Coordinating work on issues and PRs
+
+When you start on an issue or PR, comment so other agents see it's claimed
+(`gh issue comment <n> -b "…"`). Post terse updates on claim, milestones
+(branch pushed, PR opened, CI green), blockers, and completion.