universal-dev-security 1.0.0__tar.gz → 1.0.1__tar.gz

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 Semantic Versioning (PEP 440 pre-release suffixes).
 
+## [1.0.1] — 2026-11-14
+
+### Added
+- `docs/getting-started.md`: step-by-step guide from installation to a protected project,
+  with real example output; linked from the README.
+- README links are absolute so they work on the PyPI project page.
+
+### Changed
+- `uds hooks install` now embeds the current Python interpreter by default (Git hooks are never
+  committed, so the machine-specific path is safe), with `uds` on PATH as fallback. Previously a
+  hook relying only on PATH blocked every commit made without the virtual environment
+  activated. Use `--path-only` for the old behavior.
+
 ## [1.0.0] — 2026-11-14
 
 First stable release. Includes everything in 1.0.0rc1 plus improvements from the

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/DEVELOPMENT_STATUS.md

@@ -1,6 +1,6 @@
 # Development Status
 
-**Current version:** `1.0.0` — first stable release (tag `v1.0.0`). Previous: `1.0.0rc1` GitHub pre-release.
+**Current version:** `1.0.1` (tag `v1.0.1`). Previous: `1.0.0` (first stable, GitHub + PyPI), `1.0.0rc1` pre-release.
 **Last updated:** 2026-11-14
 **Previous version:** 0.4.1 (original source archived at `dist/uds-0.4.1-original-source-backup.zip`, git-ignored)
 
@@ -67,13 +67,13 @@
 5. `install.sh` is written for Linux/macOS and has not been executed.
 6. Python 3.15 is newer than some packages support (PyYAML, Semgrep wheels); UDS itself is
    dependency-free and works on 3.11–3.15.
-7. `uds update check --source pypi` will only be meaningful once UDS is published under that name;
-   until then use `--source github:OWNER/REPO`.
+7. ~~PyPI not published~~ — published 2026-11-14 via Trusted Publishing; PyPI files are identical
+   to the GitHub release assets (verified SHA-256), and `pip install universal-dev-security` was tested.
 
 ## Pending decisions (need maintainer approval)
 
-- Publishing the `v1.0.0` GitHub release (tag pushed; assets uploaded by the maintainer).
-- PyPI publication (not done).
+- Publishing `v1.0.1`: GitHub release (maintainer) and PyPI (maintainer runs the publish workflow).
+- `1.0.0` is published on GitHub and PyPI.
 - Private vulnerability reporting is enabled (verified via API); secret-scanning push protection
   was enabled by the maintainer but cannot be verified without repository-admin authentication.
 
@@ -84,3 +84,4 @@
 3. Pin GitHub Actions to commit SHAs in both workflows.
 4. Optional offline mode for OSV-Scanner (local databases) to avoid sending package metadata.
 5. Hosted web dashboard consuming report schema 2.0 (with authentication and authorization).
+6. ~~README links on PyPI~~ — fixed in 1.0.1 (absolute links).

{universal_dev_security-1.0.0/src/universal_dev_security.egg-info → universal_dev_security-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-dev-security
-Version: 1.0.0
+Version: 1.0.1
 Summary: One security system for every project: secrets, code, dependency and configuration scanning with a central policy engine, Git and AI-agent guards, and a local security dashboard.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/jet1x/Universal-Dev-Security
@@ -39,8 +39,8 @@ industry-standard scanners on any project, normalizes their results into one
 schema, enforces a central security policy for Git and AI coding agents, and
 produces a dark, self-contained HTML security dashboard.
 
-> **Status:** `1.0.0` — first stable release. See
-> [DEVELOPMENT_STATUS.md](DEVELOPMENT_STATUS.md) for verified functionality,
+> **Status:** `1.0.1` — stable. See
+> [DEVELOPMENT_STATUS.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/DEVELOPMENT_STATUS.md) for verified functionality,
 > known issues and test results. UDS reports what its scanners find; a clean
 > result is never proof that a project is secure.
 
@@ -68,19 +68,24 @@ else is `unclassified`. No security score is invented.
 
 ## Quick start
 
-Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
+New to UDS? The **[Getting started guide](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)**
+walks through installation, your first scan, reading the dashboard, fixing findings and turning
+on protection, with real example output.
 
-```powershell
-# Windows (from a release folder containing the wheel and SHA256SUMS)
-.\scripts\install.ps1 -Wheel .\dist\1.0.0\universal_dev_security-1.0.0-py3-none-any.whl
-```
+Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
 
 ```bash
-# Linux / macOS
-sh scripts/install.sh --wheel dist/1.0.0/universal_dev_security-1.0.0-py3-none-any.whl
+python -m pip install universal-dev-security
 ```
 
-Then, inside a project:
+The package on [PyPI](https://pypi.org/project/universal-dev-security/) is identical to the
+assets of the [GitHub release](https://github.com/jet1x/Universal-Dev-Security/releases)
+(same SHA-256). Prefer an isolated install? Use `pipx install universal-dev-security`, or the
+checksum-verifying installers described in
+[docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md).
+
+Install at least [Gitleaks](https://github.com/gitleaks/gitleaks#installing); `uds doctor`
+shows the official install command for every scanner. Then, inside a project:
 
 ```bash
 uds doctor                 # runtime, config and scanner availability (+ official install sources)
@@ -92,19 +97,20 @@ uds integrate claude-code --apply   # enforce the UDS policy inside Claude Code
 ```
 
 Every command that changes files is a **dry run by default** and shows a diff;
-`--apply` creates a recovery checkpoint first. See [docs/installation.md](docs/installation.md)
-for scanner installation and upgrades, and [docs/commands.md](docs/commands.md) for all commands.
+`--apply` creates a recovery checkpoint first. See [docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+for scanner installation and upgrades, and [docs/commands.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md) for all commands.
 
 ## Documentation
 
-- [Installation and upgrades](docs/installation.md)
-- [Commands](docs/commands.md)
-- [Scanners, severity and privacy](docs/scanners.md)
-- [Integrations: Claude Code, GitHub, VS Code, other agents](docs/integrations.md)
-- [Architecture](docs/architecture.md)
-- [Security model](docs/security-model.md) and [global policy](policies/GLOBAL_SECURITY_POLICY.md)
-- [Dashboard design system](docs/dashboard-design-system.md)
-- [Release process](docs/release.md)
+- [Getting started](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)
+- [Installation and upgrades](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+- [Commands](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md)
+- [Scanners, severity and privacy](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/scanners.md)
+- [Integrations: Claude Code, GitHub, VS Code, other agents](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/integrations.md)
+- [Architecture](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/architecture.md)
+- [Security model](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/security-model.md) and [global policy](https://github.com/jet1x/Universal-Dev-Security/blob/main/policies/GLOBAL_SECURITY_POLICY.md)
+- [Dashboard design system](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/dashboard-design-system.md)
+- [Release process](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/release.md)
 
 ## Safety guarantees
 
@@ -120,9 +126,9 @@ repository-level protections (for example GitHub push protection) enabled too.
 
 ## Contributing and security
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
-Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+See [CONTRIBUTING.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CONTRIBUTING.md) and [SECURITY.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/SECURITY.md).
+Changes are listed in [CHANGELOG.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CHANGELOG.md).
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE).
+Apache License 2.0. See [LICENSE](https://github.com/jet1x/Universal-Dev-Security/blob/main/LICENSE).

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/README.md

@@ -7,8 +7,8 @@ industry-standard scanners on any project, normalizes their results into one
 schema, enforces a central security policy for Git and AI coding agents, and
 produces a dark, self-contained HTML security dashboard.
 
-> **Status:** `1.0.0` — first stable release. See
-> [DEVELOPMENT_STATUS.md](DEVELOPMENT_STATUS.md) for verified functionality,
+> **Status:** `1.0.1` — stable. See
+> [DEVELOPMENT_STATUS.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/DEVELOPMENT_STATUS.md) for verified functionality,
 > known issues and test results. UDS reports what its scanners find; a clean
 > result is never proof that a project is secure.
 
@@ -36,19 +36,24 @@ else is `unclassified`. No security score is invented.
 
 ## Quick start
 
-Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
+New to UDS? The **[Getting started guide](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)**
+walks through installation, your first scan, reading the dashboard, fixing findings and turning
+on protection, with real example output.
 
-```powershell
-# Windows (from a release folder containing the wheel and SHA256SUMS)
-.\scripts\install.ps1 -Wheel .\dist\1.0.0\universal_dev_security-1.0.0-py3-none-any.whl
-```
+Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
 
 ```bash
-# Linux / macOS
-sh scripts/install.sh --wheel dist/1.0.0/universal_dev_security-1.0.0-py3-none-any.whl
+python -m pip install universal-dev-security
 ```
 
-Then, inside a project:
+The package on [PyPI](https://pypi.org/project/universal-dev-security/) is identical to the
+assets of the [GitHub release](https://github.com/jet1x/Universal-Dev-Security/releases)
+(same SHA-256). Prefer an isolated install? Use `pipx install universal-dev-security`, or the
+checksum-verifying installers described in
+[docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md).
+
+Install at least [Gitleaks](https://github.com/gitleaks/gitleaks#installing); `uds doctor`
+shows the official install command for every scanner. Then, inside a project:
 
 ```bash
 uds doctor                 # runtime, config and scanner availability (+ official install sources)
@@ -60,19 +65,20 @@ uds integrate claude-code --apply   # enforce the UDS policy inside Claude Code
 ```
 
 Every command that changes files is a **dry run by default** and shows a diff;
-`--apply` creates a recovery checkpoint first. See [docs/installation.md](docs/installation.md)
-for scanner installation and upgrades, and [docs/commands.md](docs/commands.md) for all commands.
+`--apply` creates a recovery checkpoint first. See [docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+for scanner installation and upgrades, and [docs/commands.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md) for all commands.
 
 ## Documentation
 
-- [Installation and upgrades](docs/installation.md)
-- [Commands](docs/commands.md)
-- [Scanners, severity and privacy](docs/scanners.md)
-- [Integrations: Claude Code, GitHub, VS Code, other agents](docs/integrations.md)
-- [Architecture](docs/architecture.md)
-- [Security model](docs/security-model.md) and [global policy](policies/GLOBAL_SECURITY_POLICY.md)
-- [Dashboard design system](docs/dashboard-design-system.md)
-- [Release process](docs/release.md)
+- [Getting started](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)
+- [Installation and upgrades](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+- [Commands](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md)
+- [Scanners, severity and privacy](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/scanners.md)
+- [Integrations: Claude Code, GitHub, VS Code, other agents](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/integrations.md)
+- [Architecture](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/architecture.md)
+- [Security model](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/security-model.md) and [global policy](https://github.com/jet1x/Universal-Dev-Security/blob/main/policies/GLOBAL_SECURITY_POLICY.md)
+- [Dashboard design system](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/dashboard-design-system.md)
+- [Release process](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/release.md)
 
 ## Safety guarantees
 
@@ -88,9 +94,9 @@ repository-level protections (for example GitHub push protection) enabled too.
 
 ## Contributing and security
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
-Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+See [CONTRIBUTING.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CONTRIBUTING.md) and [SECURITY.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/SECURITY.md).
+Changes are listed in [CHANGELOG.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CHANGELOG.md).
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE).
+Apache License 2.0. See [LICENSE](https://github.com/jet1x/Universal-Dev-Security/blob/main/LICENSE).

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/commands.md

@@ -52,7 +52,7 @@ incomplete with `--require-complete`, or invalid input.
 
 | Command | Purpose |
 |---|---|
-| `uds hooks install [PATH] [--apply] [--python-path]` | Install `pre-commit` and `pre-push` hooks |
+| `uds hooks install [PATH] [--apply] [--path-only]` | Install `pre-commit` and `pre-push` hooks (embed this Python interpreter, with `uds` on PATH as fallback; `--path-only` uses PATH only) |
 | `uds hooks uninstall [PATH] [--apply]` | Remove UDS-owned hooks only |
 | `uds hooks status [PATH]` | Show hook state (`uds`, `foreign`, `missing`) |
 | `uds hook git-pre-commit` / `git-pre-push` | Hook entry points (called by Git) |

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/dashboard-design-system.md

@@ -1,6 +1,6 @@
 # UDS Dashboard Design System
 
-Version: 1.0.0
+Version: 1.0.1
 
 ## Product surfaces
 

universal_dev_security-1.0.1/docs/getting-started.md

@@ -0,0 +1,176 @@
+# Getting started
+
+This guide takes you from installation to a protected project in about ten minutes.
+UDS runs locally: it checks your project with established security scanners, shows the
+results in one dashboard, and can stop mistakes such as committing a password before they
+happen.
+
+## 1. Install UDS
+
+You need Python 3.11 or newer.
+
+```bash
+python -m pip install universal-dev-security
+```
+
+Check what is available on your machine:
+
+```bash
+uds doctor
+```
+
+```text
+UDS 1.0.1 · Python 3.12.4 · Windows 11
+Git available: yes
+Project config: not initialized
+Scanners:
+  Gitleaks     OK 8.30.1
+  Semgrep      not installed
+               install: python -m pip install semgrep  (inside the UDS virtual environment)
+  OSV-Scanner  not installed
+               install: winget install --id Google.OSVScanner -e  or download from https://github.com/google/osv-scanner/releases
+  Trivy        not installed
+               install: winget install --id AquaSecurity.Trivy -e
+UDS runtime: OK (no network access used, no global settings modified)
+```
+
+## 2. Install the scanners you want
+
+UDS never installs software for you. `uds doctor` prints the official install command for
+your operating system. What each scanner adds:
+
+| Scanner | Finds | Recommended |
+|---|---|---|
+| **Gitleaks** | Passwords, API keys and tokens in your files | **Yes — the minimum** |
+| Semgrep | Risky code patterns (injection, unsafe functions, …) | Yes |
+| Trivy | Vulnerable libraries and insecure Docker / Kubernetes / Terraform configuration | Yes |
+| OSV-Scanner | Vulnerable libraries (a second, independent database) | Optional — sends package names and versions to osv.dev, so it only runs when you allow network use |
+
+Run `uds doctor` again afterwards; installed scanners show `OK`.
+
+## 3. Scan a project
+
+```bash
+cd path/to/your-project
+uds scan
+```
+
+```text
+UDS scan 20261114T121420244950Z-edd0df · path/to/your-project
+Overall status: FINDINGS
+  gitleaks     clean               0  No findings reported by Gitleaks.
+  semgrep      not_installed       -  Semgrep was not found. See https://semgrep.dev/docs/getting-started/quickstart ...
+  osv-scanner  not_installed       -  OSV-Scanner was not found. See https://google.github.io/osv-scanner/installation/ ...
+  trivy        findings            9  9 finding(s) reported by Trivy.
+Findings: critical 0, high 3, medium 6, low 0, unclassified 0 (total 9)
+Report (json): path/to/your-project/.uds/reports/security-report.json
+Report (html): path/to/your-project/.uds/reports/security-report.html
+```
+
+What happened:
+
+1. UDS detected the project's technologies (Python, Next.js, Docker, …).
+2. It ran only the scanners that apply to them, and says clearly which ones did not run.
+3. It wrote a JSON report and an HTML dashboard to `.uds/reports/` (excluded from Git).
+
+To include OSV-Scanner, approve its network use explicitly: `uds scan --allow-network`.
+
+## 4. Read the results
+
+```bash
+uds dashboard --open
+```
+
+The dashboard opens in your browser (it works offline and loads nothing from the internet):
+
+- **Findings by severity** — critical, high, medium, low, and *unclassified* when the scanner
+  gives no severity. UDS never invents a severity or a "security score".
+- **Recommendations** — what to do first, for example *"Upgrade jinja2 → 2.10.1"* or
+  *"Rotate 1 credential found in Git-tracked files"*.
+- **Findings** — search and filter; open a finding to see the file, line, explanation, fix and
+  references. Secrets are marked **in Git** (already shared — rotate them) or **local only**.
+- **Change since previous scan** — what is new and what was fixed since your last `uds scan`.
+
+Secret values are never shown — only the file and line where they are.
+
+## 5. Fix what was found
+
+- **Vulnerable library:** upgrade it to the version shown, then run your tests (`uds test`).
+- **Secret in a file:** move it to an environment variable or a secret manager. If it was ever
+  committed or shared, also **revoke or rotate it** with the service that issued it.
+- **Code or configuration issue:** follow the remediation shown in the finding.
+
+UDS can apply a few safe fixes itself, such as adding `.env` files to `.gitignore`:
+
+```bash
+uds fix            # shows what it would change
+uds fix --apply    # applies it, runs your tests, and undoes the change if they fail
+```
+
+Then run `uds scan` again to confirm.
+
+## 6. Prevent new problems
+
+### Block secrets before they reach Git
+
+```bash
+uds hooks install --apply
+```
+
+From now on a commit that contains a secret is stopped:
+
+```text
+$ git commit -m "add settings"
+UDS: 1 potential secret(s) found in staged changes (Gitleaks). Blocked.
+  - generic-api-key: settings.py:1
+UDS: remove the secret, rotate it if it was ever pushed, and use environment variables or a secret manager.
+```
+
+Pushes are checked the same way. Existing Git hooks are never overwritten.
+
+### Keep AI coding assistants within safe limits (Claude Code)
+
+```bash
+uds integrate claude-code --apply
+```
+
+Claude Code will then ask for your approval before `git push`, recursive deletes or reading
+`.env` files, and is blocked from writing credentials into files or bypassing Git hooks with
+`--no-verify`. Restart Claude Code after installing. Other agents can use the same policy
+through `uds guard` (see [integrations](integrations.md)).
+
+### Check every pull request on GitHub
+
+```bash
+uds integrate github --apply
+```
+
+This creates `.github/workflows/uds-security.yml`. Review it and commit it yourself — UDS never
+commits or pushes. Findings appear in the repository's *Security → Code scanning* tab.
+
+## Safety rules UDS follows
+
+- **Nothing changes without your say.** Commands that modify files show a preview first and
+  change something only with `--apply`.
+- **Everything can be undone.** Each change creates a recovery point: `uds rollback <id>`.
+- **Honest results.** A scanner that did not run is reported as such; a clean result means only
+  that the scanners that ran found nothing.
+- **Private by default.** No telemetry; nothing leaves your machine unless you allow it.
+
+## Command cheat sheet
+
+| I want to… | Command |
+|---|---|
+| See what is installed | `uds doctor` |
+| Scan the project | `uds scan` |
+| Open the results | `uds dashboard --open` |
+| Compare with the previous scan | `uds compare` |
+| Apply safe fixes | `uds fix --apply` |
+| Block secrets in commits and pushes | `uds hooks install --apply` |
+| Protect work with Claude Code | `uds integrate claude-code --apply` |
+| Check every pull request | `uds integrate github --apply` |
+| Undo a change made by UDS | `uds rollback <id>` |
+| Fail a CI job on serious findings | `uds scan --fail-on high` |
+
+Next: [all commands](commands.md) · [scanners and severity](scanners.md) ·
+[integrations](integrations.md) · [security model](security-model.md)

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/installation.md

@@ -4,10 +4,23 @@
 
 UDS requires Python 3.11 or newer and has no runtime dependencies.
 
+**From PyPI (simplest):**
+
+```bash
+python -m pip install universal-dev-security     # or: pipx install universal-dev-security
+```
+
+The PyPI files are the same files attached to the GitHub release (identical SHA-256),
+published through Trusted Publishing.
+
+**With the checksum-verifying installers** (download the wheel and `SHA256SUMS` from the
+[GitHub release](https://github.com/jet1x/Universal-Dev-Security/releases); the scripts are in the
+release's source archive):
+
 **Windows (user-level, no administrator rights):**
 
 ```powershell
-.\scripts\install.ps1 -Wheel .\dist\1.0.0\universal_dev_security-1.0.0-py3-none-any.whl
+.\scripts\install.ps1 -Wheel .\dist\1.0.1\universal_dev_security-1.0.1-py3-none-any.whl
 # optional: add the venv Scripts folder to your *user* PATH
 .\scripts\install.ps1 -Wheel <wheel> -AddToPath
 ```
@@ -15,7 +28,7 @@ UDS requires Python 3.11 or newer and has no runtime dependencies.
 **Linux / macOS:**
 
 ```bash
-sh scripts/install.sh --wheel dist/1.0.0/universal_dev_security-1.0.0-py3-none-any.whl
+sh scripts/install.sh --wheel dist/1.0.1/universal_dev_security-1.0.1-py3-none-any.whl
 export PATH="$HOME/.local/share/uds/venv/bin:$PATH"
 ```
 
@@ -54,12 +67,12 @@ as `skipped` with reason `unsupported_version`.
 
 ## Upgrade UDS
 
-1. Check: `uds update check --source github:jet1x/Universal-Dev-Security` (or `--source pypi` once published). This is the
+1. Check: `uds update check --source pypi` (or `--source github:jet1x/Universal-Dev-Security`). This is the
    only command that contacts the network for updates, and only when a source is given.
 2. Read the [CHANGELOG](../CHANGELOG.md) for breaking changes.
 3. Upgrade inside the UDS virtual environment:
    - from a verified wheel: re-run the installer with the new wheel;
-   - from PyPI (once published): `python -m pip install --upgrade universal-dev-security`.
+   - from PyPI: `python -m pip install --upgrade universal-dev-security`.
 4. Run `uds doctor` and `uds scan`.
 
 Project files (`.uds/config.toml`, history, checkpoints) are compatible across

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/integrations.md

@@ -66,8 +66,8 @@ as "do not proceed". Responses never contain secret values.
 ## Git hooks
 
 ```bash
-uds hooks install --apply                 # pre-commit + pre-push
-uds hooks install --apply --python-path   # embed this interpreter (works without uds on PATH)
+uds hooks install --apply                 # pre-commit + pre-push (embeds this interpreter)
+uds hooks install --apply --path-only     # rely only on `uds` from PATH
 uds hooks status
 ```
 

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/release.md

@@ -26,6 +26,20 @@ python scripts/release.py
 - [ ] Artifacts and `SHA256SUMS` attached to a signed Git tag.
 - [ ] Private vulnerability reporting enabled on the repository (see SECURITY.md).
 
+## Publish to PyPI (Trusted Publishing)
+
+PyPI publication uses OIDC Trusted Publishing — no API token exists anywhere.
+
+One-time setup on PyPI (account with 2FA): *Your account → Publishing → Add a new pending
+publisher* with project `universal-dev-security`, owner `jet1x`, repository
+`Universal-Dev-Security`, workflow `publish-pypi.yml`, environment `pypi`.
+
+For each release: publish the GitHub release with its assets and `SHA256SUMS` first, then run
+*Actions → publish to PyPI → Run workflow* with the tag. The workflow downloads the release
+assets, verifies them against `SHA256SUMS`, runs `twine check --strict`, and uploads exactly
+those files, so PyPI and GitHub serve identical artifacts. PyPI files are immutable: a mistake
+requires a new version number.
+
 ## Versioning
 
 Semantic Versioning. Pre-releases use PEP 440 suffixes (`1.0.0rc1`). The JSON

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/docs/scanners.md

@@ -5,7 +5,7 @@
 | Scanner | Category | Minimum | Verified with | Applies when | Network behavior |
 |---|---|---|---|---|---|
 | Gitleaks | Secrets | 8.19.0 (`gitleaks dir`) | 8.30.1 (real binary) | Always | Fully offline |
-| Semgrep | Code (SAST) | 1.0.0 | Fixtures only (see DEVELOPMENT_STATUS) | Source code present | Downloads registry rule packs; UDS forces `--metrics=off`; source is not uploaded |
+| Semgrep | Code (SAST) | 1.0.0 | CI (latest PyPI release, self-scan) | Source code present | Downloads registry rule packs; UDS forces `--metrics=off`; source is not uploaded |
 | OSV-Scanner | Dependencies | 1.4.0 (v1 and v2 CLI) | 2.7.1 (real binary) | Manifests/lockfiles present | **Sends package names + versions to osv.dev** — requires `--allow-network` or `allow_network = true` |
 | Trivy | Dependencies + misconfiguration | 0.45.0 | 0.76.2 (real binary) | Manifests or Docker/IaC files present | Downloads vulnerability DB and checks; files analysed locally |
 

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/scripts/install.ps1

@@ -9,7 +9,7 @@
   -AddToPath is given (user PATH only).
 
 .EXAMPLE
-  .\scripts\install.ps1 -Wheel .\dist\1.0.0\universal_dev_security-1.0.0-py3-none-any.whl
+  .\scripts\install.ps1 -Wheel .\dist\1.0.1\universal_dev_security-1.0.1-py3-none-any.whl
 #>
 [CmdletBinding()]
 param(

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/scripts/install.sh

@@ -4,8 +4,8 @@
 # SHA256SUMS when present) or a pip specification. Does not install scanners and
 # does not modify shell profiles.
 #
-#   sh scripts/install.sh --wheel dist/1.0.0/universal_dev_security-1.0.0-py3-none-any.whl
-#   sh scripts/install.sh --spec universal-dev-security==1.0.0
+#   sh scripts/install.sh --wheel dist/1.0.1/universal_dev_security-1.0.1-py3-none-any.whl
+#   sh scripts/install.sh --spec universal-dev-security==1.0.1
 set -eu
 
 WHEEL=""

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/src/universal_dev_security/__init__.py

@@ -1,3 +1,3 @@
 """Universal Dev Security (UDS) — one security system for every project."""
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/src/universal_dev_security/cli_extra.py

@@ -195,9 +195,14 @@ def register(sub: Any, with_path: Callable[[argparse.ArgumentParser], argparse.A
     for name in ("install", "uninstall"):
         hp = with_path(hsub.add_parser(name))
         hp.add_argument("--apply", action="store_true", help="Make the change (default is a dry run)")
-        hp.add_argument("--python-path", action="store_true",
-                        help="Embed this Python interpreter in the hook instead of relying on `uds` on PATH")
-        hp.set_defaults(func=cmd_hooks)
+        # Git hooks live in .git/hooks, which is never committed, so embedding this machine's
+        # interpreter path is safe and avoids blocking commits when `uds` is not on PATH
+        # (e.g. committing from an editor without the virtual environment activated).
+        hp.add_argument("--path-only", dest="python_path", action="store_false",
+                        help="Rely only on `uds` from PATH instead of embedding this Python interpreter")
+        hp.add_argument("--python-path", dest="python_path", action="store_true",
+                        help="Embed this Python interpreter (default; kept for compatibility)")
+        hp.set_defaults(func=cmd_hooks, python_path=True)
     with_path(hsub.add_parser("status")).set_defaults(func=cmd_hooks, apply=False, python_path=False)
 
     p = sub.add_parser("integrate", help="Set up Claude Code, GitHub Actions or VS Code integration")

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1/src/universal_dev_security.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-dev-security
-Version: 1.0.0
+Version: 1.0.1
 Summary: One security system for every project: secrets, code, dependency and configuration scanning with a central policy engine, Git and AI-agent guards, and a local security dashboard.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/jet1x/Universal-Dev-Security
@@ -39,8 +39,8 @@ industry-standard scanners on any project, normalizes their results into one
 schema, enforces a central security policy for Git and AI coding agents, and
 produces a dark, self-contained HTML security dashboard.
 
-> **Status:** `1.0.0` — first stable release. See
-> [DEVELOPMENT_STATUS.md](DEVELOPMENT_STATUS.md) for verified functionality,
+> **Status:** `1.0.1` — stable. See
+> [DEVELOPMENT_STATUS.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/DEVELOPMENT_STATUS.md) for verified functionality,
 > known issues and test results. UDS reports what its scanners find; a clean
 > result is never proof that a project is secure.
 
@@ -68,19 +68,24 @@ else is `unclassified`. No security score is invented.
 
 ## Quick start
 
-Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
+New to UDS? The **[Getting started guide](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)**
+walks through installation, your first scan, reading the dashboard, fixing findings and turning
+on protection, with real example output.
 
-```powershell
-# Windows (from a release folder containing the wheel and SHA256SUMS)
-.\scripts\install.ps1 -Wheel .\dist\1.0.0\universal_dev_security-1.0.0-py3-none-any.whl
-```
+Requirements: Python 3.11+, Windows, Linux or macOS. Git is recommended.
 
 ```bash
-# Linux / macOS
-sh scripts/install.sh --wheel dist/1.0.0/universal_dev_security-1.0.0-py3-none-any.whl
+python -m pip install universal-dev-security
 ```
 
-Then, inside a project:
+The package on [PyPI](https://pypi.org/project/universal-dev-security/) is identical to the
+assets of the [GitHub release](https://github.com/jet1x/Universal-Dev-Security/releases)
+(same SHA-256). Prefer an isolated install? Use `pipx install universal-dev-security`, or the
+checksum-verifying installers described in
+[docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md).
+
+Install at least [Gitleaks](https://github.com/gitleaks/gitleaks#installing); `uds doctor`
+shows the official install command for every scanner. Then, inside a project:
 
 ```bash
 uds doctor                 # runtime, config and scanner availability (+ official install sources)
@@ -92,19 +97,20 @@ uds integrate claude-code --apply   # enforce the UDS policy inside Claude Code
 ```
 
 Every command that changes files is a **dry run by default** and shows a diff;
-`--apply` creates a recovery checkpoint first. See [docs/installation.md](docs/installation.md)
-for scanner installation and upgrades, and [docs/commands.md](docs/commands.md) for all commands.
+`--apply` creates a recovery checkpoint first. See [docs/installation.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+for scanner installation and upgrades, and [docs/commands.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md) for all commands.
 
 ## Documentation
 
-- [Installation and upgrades](docs/installation.md)
-- [Commands](docs/commands.md)
-- [Scanners, severity and privacy](docs/scanners.md)
-- [Integrations: Claude Code, GitHub, VS Code, other agents](docs/integrations.md)
-- [Architecture](docs/architecture.md)
-- [Security model](docs/security-model.md) and [global policy](policies/GLOBAL_SECURITY_POLICY.md)
-- [Dashboard design system](docs/dashboard-design-system.md)
-- [Release process](docs/release.md)
+- [Getting started](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/getting-started.md)
+- [Installation and upgrades](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/installation.md)
+- [Commands](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/commands.md)
+- [Scanners, severity and privacy](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/scanners.md)
+- [Integrations: Claude Code, GitHub, VS Code, other agents](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/integrations.md)
+- [Architecture](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/architecture.md)
+- [Security model](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/security-model.md) and [global policy](https://github.com/jet1x/Universal-Dev-Security/blob/main/policies/GLOBAL_SECURITY_POLICY.md)
+- [Dashboard design system](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/dashboard-design-system.md)
+- [Release process](https://github.com/jet1x/Universal-Dev-Security/blob/main/docs/release.md)
 
 ## Safety guarantees
 
@@ -120,9 +126,9 @@ repository-level protections (for example GitHub push protection) enabled too.
 
 ## Contributing and security
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
-Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+See [CONTRIBUTING.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CONTRIBUTING.md) and [SECURITY.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/SECURITY.md).
+Changes are listed in [CHANGELOG.md](https://github.com/jet1x/Universal-Dev-Security/blob/main/CHANGELOG.md).
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE).
+Apache License 2.0. See [LICENSE](https://github.com/jet1x/Universal-Dev-Security/blob/main/LICENSE).

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/src/universal_dev_security.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ pyproject.toml
 docs/architecture.md
 docs/commands.md
 docs/dashboard-design-system.md
+docs/getting-started.md
 docs/installation.md
 docs/integrations.md
 docs/release.md

{universal_dev_security-1.0.0 → universal_dev_security-1.0.1}/tests/test_gitguard.py

@@ -131,3 +131,15 @@ def test_hook_install_is_recoverable(repo):
     restore = RecoveryManager(repo).restore(result["checkpoint"])
     assert restore["status"] == "restored"
     assert not (repo / ".git" / "hooks" / "pre-commit").exists()
+
+
+def test_cli_hooks_embed_interpreter_by_default(repo, capsys):
+    # Regression (found while writing the getting-started guide): hooks that relied only on
+    # `uds` from PATH blocked every commit made outside the activated virtual environment.
+    from universal_dev_security.cli import main
+    assert main(["hooks", "install", str(repo), "--apply"]) == 0
+    script = (repo / ".git" / "hooks" / "pre-commit").read_text(encoding="utf-8")
+    assert "UDS_PY=" in script and "command -v uds" in script  # interpreter first, PATH fallback
+    main(["hooks", "uninstall", str(repo), "--apply"])
+    assert main(["hooks", "install", str(repo), "--apply", "--path-only"]) == 0
+    assert "UDS_PY=" not in (repo / ".git" / "hooks" / "pre-commit").read_text(encoding="utf-8")