kanon-cli 3.1.1__tar.gz → 3.3.0__tar.gz

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/CHANGELOG.md

@@ -2,8 +2,205 @@
 
 
 
+## v3.3.0 (2026-07-17)
+
+### Feature
+
+* feat: kanon list command + usage telemetry, full install-graph capture, and update-warning enhancement (#91)
+
+* feat: add usage telemetry, full install-graph capture, and update-warning enhancement
+
+Emit one structured usage-telemetry event per CLI command to the Caylent
+collector, fully capturing what was installed (every direct source plus every
+transitive repo package with URLs and resolved content SHAs), and enhance the
+"update available" warning.
+
+Telemetry (new core/telemetry.py):
+- Hooked via try/finally around dispatch in cli.py; captures command, subcommand,
+  boolean flag names, allowlisted flag values, outcome (exit code/status/error
+  class/duration), runtime environment, and credential-stripped git provenance.
+- OTLP/HTTP logs JSON with one log record whose body is a flat
+  {tool,timestamp,event_type,payload} object (payload a JSON string); POSTed via
+  stdlib urllib in a detached, non-blocking, silent, never-fail background
+  process (utils/spawn.spawn_detached), HTTPS-only guard, timeouts + body cap.
+- Auto opted-in by default; the only opt-out is KANON_TELEMETRY_DISABLED (no
+  --no-telemetry flag). KANON_TELEMETRY_ENDPOINT / --telemetry-endpoint and
+  KANON_TELEMETRY_DEBUG / --telemetry-debug are supported.
+- Zero-secret allowlist: never raw argv, keys, tokens, credentials, env-var
+  values, or file contents; every URL is credential-stripped.
+
+Full install-graph capture (core/install.py):
+- Populate SourceEntry.projects on install by resolving project -> remote -> URL
+  from the already-synced manifests (walk_includes_collecting_remotes +
+  join_project_repo_url + canonicalize_repo_url) joined with the captured content
+  pins. This also fixes `kanon why` showing an empty project layer on
+  install-written lockfiles. Telemetry emits payload.install_graph and a
+  flattened payload.installed_packages[] (direct + transitive), capped under the
+  collector body limit with install_graph_truncated on overflow.
+
+Update-warning enhancement (core/update_check.py):
+- Yellow banner with the current version in red and the latest in green; a red
+  "no internet access -- could not check for updates" notice on a failed fetch,
+  shown at most once per window; default KANON_UPDATE_CHECK_TTL lowered to 3h.
+
+Docs: new docs/privacy.md (collected fields, encryption, opt-out) linked from
+README; telemetry rows in docs/cli-reference.md and docs/configuration.md;
+regenerated help + completion snapshots.
+
+* test: include telemetry global flags in bash completion expectation
+
+The new --telemetry-debug / --telemetry-endpoint global flags now appear in the
+top-level bash completion, so the exact-match global_flags row in
+test_completion_bash.py is extended to include them.
+
+* test: use provider-neutral remote name in build_project_entries fixture
+
+The provider-agnostic host gate forbids the bare token 'gh'; rename the fixture
+manifest remote from 'gh' to 'origin' so the manifest XML fixtures carry no
+provider-specific reference.
+
+* fix: record real command outcome in telemetry and emit for --version/--help/bare invocations
+
+* feat: add kanon list command (declared vs installed source inventory)
+
+Add `kanon list`, the flat inventory command that reconciles the sources
+declared in .kanon against those installed in .kanon.lock and tags each one
+installed / not-installed / orphan -- the kanon analogue of `pip list` /
+`npm ls` / `poetry show`.
+
+Flags: --declared, --tree, --status <installed|not-installed|orphan>,
+--format <table|json>, --kanon-file, --lock-file. Every failure path yields a
+clean single-prefixed ERROR (no traceback). The command emits usage telemetry
+like every other command (command=list, --tree flag, --format/--status values
+via the flag-value allowlist).
+
+The declared-vs-installed partition reuses a new non-raising
+reconcile_declared_installed() extracted from check_lockfile_consistency (one
+source of truth). Covered by unit/functional/integration/scenario tests plus a
+real-git add->install->edit->list journey; list.py at 100% coverage. Help and
+shell-completion snapshots and docs updated.
+
+The 3.0.0 list->search rename left guards asserting `list` is an unknown
+command; those are updated to reflect `list` now being a distinct command.
+
+* test: isolate test subprocesses from coverage subprocess measurement
+
+Under `pytest --cov` (make test) pytest-cov and coverage export COV_CORE_* /
+COVERAGE_PROCESS_* so spawned subprocesses auto-start coverage. A measured
+`kanon` subprocess then writes a .coverage-data directory into its working
+directory -- resolved relative to the child CWD on some filesystems -- which
+behavioural subprocess tests that inspect the child filesystem
+(`kanon repo status --orphans`) or parse its stderr (`--telemetry-debug` JSON)
+then trip over, non-deterministically across OS / filesystem.
+
+Strip the coverage subprocess-trigger variables from the child environment in
+the functional and scenario subprocess runners and the telemetry-journey env
+builder via a shared strip_subprocess_coverage_env helper. Behavioural CLI
+subprocess tests do not need coverage of the child; the 90% coverage gate is
+measured in-process on the unit tier, which uses its own runner and is
+unaffected. ([`57246f8`](https://github.com/caylent-solutions/kanon/commit/57246f8a8a46b99ad2b35a954289d7a9e7d1966c))
+
+
+## v3.2.0 (2026-07-13)
+
+### Chore
+
+* chore(release): 3.2.0 ([`b503e3c`](https://github.com/caylent-solutions/kanon/commit/b503e3cf92479b6192b186ad6b2481563c916074))
+
+### Feature
+
+* feat(clean): ~/.kanon-home store rename, .kanon-dir guard, --purge/--purge-all (store-only teardown with no .kanon), no unconditional .gitignore (#89)
+
+* feat(clean): add --purge/--purge-all; default home store to ~/.kanon-home; clean error when .kanon is a directory
+
+Three related changes so kanon works cleanly from any directory (including
+$HOME) and can be fully torn down with the tool:
+
+- Rename the default home store directory from ~/.kanon to ~/.kanon-home so it
+  no longer collides with the project .kanon config file. Running kanon from
+  $HOME previously crashed with a cryptic "Is a directory". Only the default
+  changes; the --home/--store-dir flag and KANON_HOME env are unchanged. No
+  auto-migration: a leftover ~/.kanon store is an orphaned cache, safe to delete.
+
+- When a writer (add / remove / marketplace enable|disable) must read or write
+  the .kanon config FILE but finds a .kanon DIRECTORY there, fail fast with a
+  clean, actionable error naming the exact rm -rf <path> command and telling the
+  user to re-run, instead of the cryptic IsADirectoryError.
+
+- Add kanon clean --purge (also delete this project's .kanon and .kanon.lock)
+  and kanon clean --purge-all (also remove the shared KANON_HOME store dir).
+  --purge-all validates it removes ONLY kanon-owned content: it refuses unsafe
+  KANON_HOME paths (filesystem root, your home, or a parent of home/cwd), removes
+  only the store/ and cache/ subdirs, and removes the home root only when empty;
+  any non-kanon entries are kept with a warning.
+
+Tests: unit + integration + functional for all three changes (the
+directory-collision guard for all writers and the --purge-all safety refusals
+included). Docs and the clean/toplevel --help snapshots updated.
+
+* test(clean): sync completion goldens and stub signature for --purge flags
+
+The new kanon clean --purge / --purge-all flags changed the bash and zsh
+shell-completion output, so regenerate the committed golden fixtures. Also
+extend the clean() side-effect stub in the path-resolution integration test
+to accept the new purge / purge_home keyword arguments, matching the updated
+core clean() signature.
+
+* fix(clean): remove the shared home store on --purge-all even when no .kanon is present
+
+kanon clean --purge-all is machine-global: it must tear down the shared
+KANON_HOME store even when there is no discoverable project .kanon (for example
+right after kanon clean --purge deleted it). Previously it failed with
+"No .kanon file found ..." and left ~/.kanon-home in place.
+
+_run now detects the no-usable-.kanon case (auto-discovery FileNotFoundError, or
+an explicit path that is not a file) and, when --purge-all is set, removes only
+the shared home store via remove_kanon_home_store(), preserving every safety
+refusal (filesystem root, the user home directory, an ancestor of the home or
+current directory). Plain clean and --purge without --purge-all still require a
+discoverable .kanon.
+
+Regenerates the clean help snapshot and the zsh completion golden for the
+updated --purge-all help text.
+
+* fix(install): stop writing an unconditional .gitignore; keep only the in-git-repo store safety net
+
+In the 3.x store model both gitignore writes targeted <KANON_HOME>/store/.gitignore.
+kanon install wrote .packages/ and .kanon-data/ into that file unconditionally,
+littering a .gitignore even for the default ~/.kanon-home (which is not a git
+repo). Remove the unconditional write.
+
+The store safety net (write_store_gitignore_if_in_git_repo) is retained: kanon
+still writes <KANON_HOME>/store/.gitignore containing "*" ONLY when the store
+sits inside a git working tree, so a KANON_HOME inside a repo never commits the
+fetched-artifact cache (spec Section 3.5). With the default ~/.kanon-home, kanon
+writes no .gitignore at all.
+
+update_gitignore now requires its entries argument (the removed default was the
+only unconditional caller). Tests that asserted the removed unconditional write
+now assert the new behavior (no .gitignore for a non-git store); the append-helper
+mechanics tests pass explicit entries; the safety-net tests are unchanged.
+
+Docs (how-it-works, architecture, lifecycle, integration-testing) updated;
+lifecycle also documents clean --purge-all running without a .kanon.
+
+---------
+
+Co-authored-by: t <t@e.x> ([`d9b0ad1`](https://github.com/caylent-solutions/kanon/commit/d9b0ad1856ab58487b7ed3efdc3ff9d87b60b193))
+
+### Unknown
+
+* Merge pull request #90 from caylent-solutions/release-3.2.0
+
+Release 3.2.0 ([`fb944e2`](https://github.com/caylent-solutions/kanon/commit/fb944e251cf650020070e29cb28a26cbffc886da))
+
+
 ## v3.1.1 (2026-06-27)
 
+### Chore
+
+* chore(release): 3.1.1 ([`890b026`](https://github.com/caylent-solutions/kanon/commit/890b026b47ca8820b41ca8d218658e50691254a2))
+
 ### Fix
 
 * fix: outdated handles namespaced/bare exact tags; why disambiguates same-URL sources (#87)
@@ -31,6 +228,12 @@ distinct alias tokens + alias round-trip for why).
 
 Co-authored-by: t <t@e.x> ([`0d45f67`](https://github.com/caylent-solutions/kanon/commit/0d45f673243861b0aaef823f6d95e0a548c447d4))
 
+### Unknown
+
+* Merge pull request #88 from caylent-solutions/release-3.1.1
+
+Release 3.1.1 ([`cec7213`](https://github.com/caylent-solutions/kanon/commit/cec7213109c0e307e80751e728c6a59751e20794))
+
 
 ## v3.1.0 (2026-06-27)
 

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.1.1
+Version: 3.3.0
 Summary: Kanon (Kanon Package Manager) CLI tool
 Project-URL: Homepage, https://github.com/caylent-solutions/kanon
 Project-URL: Issues, https://github.com/caylent-solutions/kanon/issues
@@ -55,6 +55,7 @@ via declarative manifests.
   - [kanon remove](#kanon-remove)
   - [kanon install](#kanon-install)
   - [kanon clean](#kanon-clean)
+  - [kanon list](#kanon-list)
   - [kanon outdated](#kanon-outdated)
   - [kanon why](#kanon-why)
   - [kanon doctor](#kanon-doctor)
@@ -183,7 +184,7 @@ git commit -m "feat: add my-package 1.2.3"
 
 Committing both files ensures the entire team installs the same resolved
 package versions. The synced artifacts live in the shared `KANON_HOME`
-store (`~/.kanon` by default), never in your project, so there is nothing
+store (`~/.kanon-home` by default), never in your project, so there is nothing
 package-related to commit beyond `.kanon` and `.kanon.lock`.
 
 ---
@@ -208,6 +209,7 @@ persistent installation and advanced options, see
 | `kanon search` | List packages available in a catalog or show detail for one | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon add` | Add a package (with optional version constraint) to `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon remove` | Remove a package from `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
+| `kanon list` | List sources declared in `.kanon` vs installed in `.kanon.lock` (installed / not-installed / orphan) | [docs/cli-reference.md](docs/cli-reference.md#kanon-list) |
 | `kanon outdated` | Show packages in `.kanon` that have newer versions available | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon why` | Explain why a specific package version was resolved | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon install` | Resolve, clone, and symlink all packages; writes `.kanon.lock` | [docs/lockfile.md](docs/lockfile.md) |
@@ -216,7 +218,7 @@ persistent installation and advanced options, see
 | `kanon validate xml` | Validate XML manifests under `repo-specs/` | [docs/repo/manifest-format.md](docs/repo/manifest-format.md) |
 | `kanon validate marketplace` | Validate marketplace XML manifests under `repo-specs/` | [docs/repo/manifest-format.md](docs/repo/manifest-format.md) |
 | `kanon validate metadata` | Validate catalog entry metadata | [docs/catalog-author-guide.md](docs/catalog-author-guide.md) |
-| `kanon clean` | Remove synced packages and Kanon state (`--orphans` also prunes unreferenced marketplaces) | [docs/lifecycle.md](docs/lifecycle.md) |
+| `kanon clean` | Remove synced packages and Kanon state (`--orphans` prunes unreferenced marketplaces; `--purge` also deletes `.kanon`/`.kanon.lock`; `--purge-all` also removes the `KANON_HOME` store) | [docs/lifecycle.md](docs/lifecycle.md) |
 | `kanon repo` | Low-level manifest-driven repo sync subsystem | [docs/repo/README.md](docs/repo/README.md) |
 | `kanon marketplace` | Manage the per-dependency Claude marketplace install flag in `.kanon` (`enable` / `disable` / `status`) | [docs/configuration.md](docs/configuration.md) |
 | `kanon completion` | Emit a shell completion script for bash, zsh, or powershell | [docs/shell-completion.md](docs/shell-completion.md) |
@@ -572,6 +574,8 @@ Executes the full teardown lifecycle.
 kanon clean                       # auto-discover .kanon by walking up from cwd
 kanon clean .kanon                # explicit path to .kanon file
 kanon clean --orphans             # also unregister orphaned marketplaces
+kanon clean --purge               # also delete .kanon and .kanon.lock
+kanon clean --purge-all           # also remove the KANON_HOME store directory
 ```
 
 **Behavior:**
@@ -585,6 +589,32 @@ With `--orphans`, before the normal teardown kanon also unregisters any
 kanon-owned marketplaces recorded in `.kanon.lock` that are no longer
 referenced by `.kanon`, pruning them from `~/.claude`.
 
+With `--purge`, kanon also deletes this project's `.kanon` and `.kanon.lock`
+files. With `--purge-all`, it additionally removes the shared `KANON_HOME`
+store directory (default `~/.kanon-home`), removing only kanon-owned content
+(`store/`, `cache/`, and the emptied root) and refusing unsafe `KANON_HOME`
+paths such as your home directory or the filesystem root.
+
+### kanon list
+
+Lists the sources declared in `.kanon` against those installed in `.kanon.lock`,
+tagging each `installed`, `not-installed`, or `orphan` -- the kanon analogue of
+`pip list` / `npm ls`.
+
+```bash
+kanon list                        # every source, declared vs installed, tagged
+kanon list --declared             # only sources declared in .kanon (no orphans)
+kanon list --status orphan        # only sources in the lock no longer declared
+kanon list --tree                 # expand installed sources to transitive packages
+kanon list --format json          # machine-readable JSON
+```
+
+A source is `installed` when it is in both files, `not-installed` when declared
+but not yet locked (run `kanon install`), and `orphan` when locked but no longer
+declared. Key options: `--declared`, `--tree`, `--status {installed,not-installed,orphan}`,
+`--format {table,json}`, `--kanon-file`, `--lock-file`. See
+[docs/cli-reference.md](docs/cli-reference.md#kanon-list).
+
 ### kanon outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -795,9 +825,9 @@ and `kanon catalog audit`. `kanon install` is hermetic: it reads only
 `.kanon` and `.kanon.lock` and does not consult a catalog source.
 
 **`KANON_HOME`**
-Root of the shared kanon store and caches (default `~/.kanon`). The
+Root of the shared kanon store and caches (default `~/.kanon-home`). The
 `--home` / `--store-dir <path>` global flag overrides it for a single
-invocation; precedence is flag > `KANON_HOME` > `~/.kanon`. Replaces the
+invocation; precedence is flag > `KANON_HOME` > `~/.kanon-home`. Replaces the
 removed `KANON_WORKSPACE_DIR` / `KANON_CACHE_DIR` variables. Synced artifacts
 and the per-`.kanon` workspace lock both live under `${KANON_HOME}/store/`,
 so the project directory holds only `.kanon` (plus `.kanon.lock` after the
@@ -900,7 +930,7 @@ regardless of which source provided each package.
 ### Directory Structure After Install
 
 Fetched artifacts live in the shared `KANON_HOME` store
-(`$KANON_HOME`, default `~/.kanon`), content-addressed and deduped across
+(`$KANON_HOME`, default `~/.kanon-home`), content-addressed and deduped across
 projects. Only `.kanon` and `.kanon.lock` live in (and are committed to)
 the project itself:
 
@@ -909,7 +939,7 @@ project/
   .kanon                            # Configuration (committed)
   .kanon.lock                       # Resolved SHAs (committed)
 
-$KANON_HOME/                        # Shared store (default ~/.kanon; not in the repo)
+$KANON_HOME/                        # Shared store (default ~/.kanon-home; not in the repo)
   store/
     .kanon-data/
       sources/
@@ -1475,6 +1505,23 @@ version bumps.
   supported; see [Platform support](#platform-support) and use WSL2)
 - [Contributing](CONTRIBUTING.md) -- How to create and maintain Kanon
   packages and marketplaces
+- [Privacy & Telemetry](docs/privacy.md) -- What usage telemetry kanon
+  collects, why, how it is encrypted, and how to turn it off
+
+---
+
+## Usage telemetry
+
+kanon emits one anonymised-by-design usage event per command to help the
+maintainers understand which commands and package sources are used. Telemetry
+is **on by default**, runs **silently** and **non-blocking**, never blocks or
+fails your command, and serialises only an explicit allowlist of kanon-computed
+fields -- never raw argv, credentials, keys, tokens, env-var values, or file
+contents (every URL is credential-stripped before it is sent).
+
+Disable it entirely by setting `KANON_TELEMETRY_DISABLED=1`. See
+[docs/privacy.md](docs/privacy.md) for the full list of collected fields and the
+transit/at-rest encryption.
 
 ---
 

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/README.md

@@ -33,6 +33,7 @@ via declarative manifests.
   - [kanon remove](#kanon-remove)
   - [kanon install](#kanon-install)
   - [kanon clean](#kanon-clean)
+  - [kanon list](#kanon-list)
   - [kanon outdated](#kanon-outdated)
   - [kanon why](#kanon-why)
   - [kanon doctor](#kanon-doctor)
@@ -161,7 +162,7 @@ git commit -m "feat: add my-package 1.2.3"
 
 Committing both files ensures the entire team installs the same resolved
 package versions. The synced artifacts live in the shared `KANON_HOME`
-store (`~/.kanon` by default), never in your project, so there is nothing
+store (`~/.kanon-home` by default), never in your project, so there is nothing
 package-related to commit beyond `.kanon` and `.kanon.lock`.
 
 ---
@@ -186,6 +187,7 @@ persistent installation and advanced options, see
 | `kanon search` | List packages available in a catalog or show detail for one | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon add` | Add a package (with optional version constraint) to `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
 | `kanon remove` | Remove a package from `.kanon` | [docs/list-and-add.md](docs/list-and-add.md) |
+| `kanon list` | List sources declared in `.kanon` vs installed in `.kanon.lock` (installed / not-installed / orphan) | [docs/cli-reference.md](docs/cli-reference.md#kanon-list) |
 | `kanon outdated` | Show packages in `.kanon` that have newer versions available | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon why` | Explain why a specific package version was resolved | [docs/outdated-and-why.md](docs/outdated-and-why.md) |
 | `kanon install` | Resolve, clone, and symlink all packages; writes `.kanon.lock` | [docs/lockfile.md](docs/lockfile.md) |
@@ -194,7 +196,7 @@ persistent installation and advanced options, see
 | `kanon validate xml` | Validate XML manifests under `repo-specs/` | [docs/repo/manifest-format.md](docs/repo/manifest-format.md) |
 | `kanon validate marketplace` | Validate marketplace XML manifests under `repo-specs/` | [docs/repo/manifest-format.md](docs/repo/manifest-format.md) |
 | `kanon validate metadata` | Validate catalog entry metadata | [docs/catalog-author-guide.md](docs/catalog-author-guide.md) |
-| `kanon clean` | Remove synced packages and Kanon state (`--orphans` also prunes unreferenced marketplaces) | [docs/lifecycle.md](docs/lifecycle.md) |
+| `kanon clean` | Remove synced packages and Kanon state (`--orphans` prunes unreferenced marketplaces; `--purge` also deletes `.kanon`/`.kanon.lock`; `--purge-all` also removes the `KANON_HOME` store) | [docs/lifecycle.md](docs/lifecycle.md) |
 | `kanon repo` | Low-level manifest-driven repo sync subsystem | [docs/repo/README.md](docs/repo/README.md) |
 | `kanon marketplace` | Manage the per-dependency Claude marketplace install flag in `.kanon` (`enable` / `disable` / `status`) | [docs/configuration.md](docs/configuration.md) |
 | `kanon completion` | Emit a shell completion script for bash, zsh, or powershell | [docs/shell-completion.md](docs/shell-completion.md) |
@@ -550,6 +552,8 @@ Executes the full teardown lifecycle.
 kanon clean                       # auto-discover .kanon by walking up from cwd
 kanon clean .kanon                # explicit path to .kanon file
 kanon clean --orphans             # also unregister orphaned marketplaces
+kanon clean --purge               # also delete .kanon and .kanon.lock
+kanon clean --purge-all           # also remove the KANON_HOME store directory
 ```
 
 **Behavior:**
@@ -563,6 +567,32 @@ With `--orphans`, before the normal teardown kanon also unregisters any
 kanon-owned marketplaces recorded in `.kanon.lock` that are no longer
 referenced by `.kanon`, pruning them from `~/.claude`.
 
+With `--purge`, kanon also deletes this project's `.kanon` and `.kanon.lock`
+files. With `--purge-all`, it additionally removes the shared `KANON_HOME`
+store directory (default `~/.kanon-home`), removing only kanon-owned content
+(`store/`, `cache/`, and the emptied root) and refusing unsafe `KANON_HOME`
+paths such as your home directory or the filesystem root.
+
+### kanon list
+
+Lists the sources declared in `.kanon` against those installed in `.kanon.lock`,
+tagging each `installed`, `not-installed`, or `orphan` -- the kanon analogue of
+`pip list` / `npm ls`.
+
+```bash
+kanon list                        # every source, declared vs installed, tagged
+kanon list --declared             # only sources declared in .kanon (no orphans)
+kanon list --status orphan        # only sources in the lock no longer declared
+kanon list --tree                 # expand installed sources to transitive packages
+kanon list --format json          # machine-readable JSON
+```
+
+A source is `installed` when it is in both files, `not-installed` when declared
+but not yet locked (run `kanon install`), and `orphan` when locked but no longer
+declared. Key options: `--declared`, `--tree`, `--status {installed,not-installed,orphan}`,
+`--format {table,json}`, `--kanon-file`, `--lock-file`. See
+[docs/cli-reference.md](docs/cli-reference.md#kanon-list).
+
 ### kanon outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -773,9 +803,9 @@ and `kanon catalog audit`. `kanon install` is hermetic: it reads only
 `.kanon` and `.kanon.lock` and does not consult a catalog source.
 
 **`KANON_HOME`**
-Root of the shared kanon store and caches (default `~/.kanon`). The
+Root of the shared kanon store and caches (default `~/.kanon-home`). The
 `--home` / `--store-dir <path>` global flag overrides it for a single
-invocation; precedence is flag > `KANON_HOME` > `~/.kanon`. Replaces the
+invocation; precedence is flag > `KANON_HOME` > `~/.kanon-home`. Replaces the
 removed `KANON_WORKSPACE_DIR` / `KANON_CACHE_DIR` variables. Synced artifacts
 and the per-`.kanon` workspace lock both live under `${KANON_HOME}/store/`,
 so the project directory holds only `.kanon` (plus `.kanon.lock` after the
@@ -878,7 +908,7 @@ regardless of which source provided each package.
 ### Directory Structure After Install
 
 Fetched artifacts live in the shared `KANON_HOME` store
-(`$KANON_HOME`, default `~/.kanon`), content-addressed and deduped across
+(`$KANON_HOME`, default `~/.kanon-home`), content-addressed and deduped across
 projects. Only `.kanon` and `.kanon.lock` live in (and are committed to)
 the project itself:
 
@@ -887,7 +917,7 @@ project/
   .kanon                            # Configuration (committed)
   .kanon.lock                       # Resolved SHAs (committed)
 
-$KANON_HOME/                        # Shared store (default ~/.kanon; not in the repo)
+$KANON_HOME/                        # Shared store (default ~/.kanon-home; not in the repo)
   store/
     .kanon-data/
       sources/
@@ -1453,6 +1483,23 @@ version bumps.
   supported; see [Platform support](#platform-support) and use WSL2)
 - [Contributing](CONTRIBUTING.md) -- How to create and maintain Kanon
   packages and marketplaces
+- [Privacy & Telemetry](docs/privacy.md) -- What usage telemetry kanon
+  collects, why, how it is encrypted, and how to turn it off
+
+---
+
+## Usage telemetry
+
+kanon emits one anonymised-by-design usage event per command to help the
+maintainers understand which commands and package sources are used. Telemetry
+is **on by default**, runs **silently** and **non-blocking**, never blocks or
+fails your command, and serialises only an explicit allowlist of kanon-computed
+fields -- never raw argv, credentials, keys, tokens, env-var values, or file
+contents (every URL is credential-stripped before it is sent).
+
+Disable it entirely by setting `KANON_TELEMETRY_DISABLED=1`. See
+[docs/privacy.md](docs/privacy.md) for the full list of collected fields and the
+transit/at-rest encryption.
 
 ---
 

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/docs/architecture.md

@@ -74,7 +74,6 @@ the source of truth for which clones exist.
 <project-root>/
   .kanon                        # operator-authored config file
   .kanon.lock                   # generated lockfile (commit this)
-  .gitignore                    # auto-updated by kanon install (idempotent)
   .kanon-data/
     .kanon-install.lock         # flock-managed concurrency lock
     sources/
@@ -97,8 +96,11 @@ Key paths:
 - **`.packages/`** -- aggregated symlinks pointing into the per-source
   `.packages/*` entries. This is the only directory operators need to
   reference in downstream tooling.
-- **`.gitignore`** -- `kanon install` appends `.packages/` and
-  `.kanon-data/` (idempotent; no duplicate entries are written).
+- **`<KANON_HOME>/store/.gitignore`** -- `kanon install` writes this
+  safety net (containing `*`) ONLY when the shared `KANON_HOME` store sits
+  inside a git working tree, so the fetched-artifact cache is never committed.
+  With the default `~/.kanon-home` (not a git repo), `kanon install` writes no
+  `.gitignore` at all.
 
 If the `.kanon-data/` directory layout becomes inconsistent (for example after
 a SIGTERM mid-clone), run `kanon clean` to prune and recover.

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/docs/catalog-author-guide.md

@@ -100,7 +100,7 @@ To audit a remote manifest repo, set `KANON_HOME` and supply the
 source in `<git_url>@<ref>` form:
 
 ```bash
-export KANON_HOME=~/.kanon
+export KANON_HOME=~/.kanon-home
 kanon catalog audit https://example.com/org/manifest-repo.git@main
 ```
 
@@ -409,7 +409,7 @@ before publishing a release. The steps assume a scratch clone at
 6. **List catalog entries via scratch source:**
 
    ```bash
-   export KANON_HOME=~/.kanon
+   export KANON_HOME=~/.kanon-home
    kanon search --catalog-source ./scratch@main
    ```
 

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/docs/cli/catalog-audit.md

@@ -171,7 +171,7 @@ spec Section 3.6 (trust model / credential isolation).
 
 The cache lives under the shared `KANON_HOME` store root. `KANON_HOME`
 resolves from the `--home` / `--store-dir` flag, then the `KANON_HOME`
-environment variable, then the `~/.kanon` default, so a remote audit target
+environment variable, then the `~/.kanon-home` default, so a remote audit target
 works without setting `KANON_HOME` explicitly.
 
 ## Source-name-derivation check (`--check source-name-derivation`)
@@ -436,7 +436,7 @@ operators encounter resolver failures:
 # Inventory non-PEP-440 tags in a local manifest repo
 kanon catalog audit --check tag-format /path/to/manifest-repo
 
-# Inventory a remote manifest repo (uses the shared KANON_HOME store; ~/.kanon by default)
+# Inventory a remote manifest repo (uses the shared KANON_HOME store; ~/.kanon-home by default)
 kanon catalog audit --check tag-format https://github.com/org/manifest-repo.git@main
 ```
 
@@ -601,7 +601,7 @@ kanon catalog audit
 # Audit an explicit local path
 kanon catalog audit /path/to/manifest-repo
 
-# Audit a remote repo (cached under the shared KANON_HOME store; ~/.kanon by default)
+# Audit a remote repo (cached under the shared KANON_HOME store; ~/.kanon-home by default)
 kanon catalog audit https://github.com/org/manifest-repo.git@main
 
 # Run only metadata and tag-format checks
@@ -624,7 +624,7 @@ kanon catalog audit https://github.com/org/repo.git@v1.0.0 \
 |----------|---------|-------------|
 | `KANON_CATALOG_AUDIT_FORMAT` | `text` | Default output format. CLI `--format` takes precedence. |
 | `KANON_CATALOG_AUDIT_CACHE_TTL_SECONDS` | `3600` | Cache TTL in seconds for remote clones. Must be a positive integer. |
-| `KANON_HOME` | `~/.kanon` | Shared kanon home (store + caches); the audit cache lives under `${KANON_HOME}/cache`. Overridden by the `--home` / `--store-dir` flag. |
+| `KANON_HOME` | `~/.kanon-home` | Shared kanon home (store + caches); the audit cache lives under `${KANON_HOME}/cache`. Overridden by the `--home` / `--store-dir` flag. |
 | `KANON_ALLOW_INSECURE_REMOTES` | (unset) | When set to `1`, suppresses R002 findings for non-HTTPS/SSH remote URLs. Any value other than `1` is treated as unset. Intended for local test fixtures only; do not set in production CI pipelines. R001 and R003 findings are never suppressed by this variable. |
 
 ## Related commands

{kanon_cli-3.1.1 → kanon_cli-3.3.0}/docs/cli/doctor.md

@@ -57,7 +57,7 @@ emitted). Exit code is 1 when any error-level finding is detected.
   recreating the directory empty with mode `0700`. Reports an info finding
   with the count of files removed. This flag is independent of the health
   checks. `KANON_HOME` resolves from the `--home` / `--store-dir` flag, the
-  `KANON_HOME` env var, then the `~/.kanon` default, so the cache directory is
+  `KANON_HOME` env var, then the `~/.kanon-home` default, so the cache directory is
   always resolved.
 
 `--prune-cache`
@@ -67,7 +67,7 @@ emitted). Exit code is 1 when any error-level finding is detected.
   stale `.kanon-data/.kanon-install.lock` files (mtime older than
   `KANON_DOCTOR_STALE_LOCK_AGE_HOURS` hours) as advisory findings -- doctor
   does NOT delete them. The cache directory is resolved from `KANON_HOME`
-  (flag, env var, or `~/.kanon` default); the stale-lock scan always runs from
+  (flag, env var, or `~/.kanon-home` default); the stale-lock scan always runs from
   the current working directory.
 
 ## Subchecks
@@ -258,7 +258,7 @@ INFO: Completion cache refreshed: 3 file(s) removed from /home/user/.kanon/cache
 ```
 
 `KANON_HOME` resolves from the `--home` / `--store-dir` flag, the `KANON_HOME`
-env var, then the `~/.kanon` default, so the completion-cache directory is
+env var, then the `~/.kanon-home` default, so the completion-cache directory is
 always resolved.
 
 ### Subcheck 7: Completion errors report
@@ -268,7 +268,7 @@ from `${KANON_HOME}/cache/completion-errors.log`. This log is written by shell
 completion callback failures (see E7 / `docs/shell-completion.md`).
 
 `kanon doctor` only reads this log -- it does NOT modify, truncate, or rotate it.
-The cache directory is resolved from `KANON_HOME` (flag, env var, or `~/.kanon`
+The cache directory is resolved from `KANON_HOME` (flag, env var, or `~/.kanon-home`
 default); when the log file does not exist this subcheck reports the info notice
 below.
 
@@ -417,7 +417,7 @@ INFO: Advisory: stale install lock found at /path/to/.kanon-data/.kanon-install.
 ```
 
 `KANON_HOME` resolves from the `--home` / `--store-dir` flag, the `KANON_HOME`
-env var, then the `~/.kanon` default, so the cache prune always runs against
+env var, then the `~/.kanon-home` default, so the cache prune always runs against
 the resolved cache directory; the stale-lock scan runs independently from the
 current working directory.
 
@@ -440,7 +440,7 @@ are emitted. Health checks (subchecks 1-5, 6, 7, 9, 11) always run after.
 | `KANON_RESOLVE_TIMEOUT` | `30` | Timeout in seconds for each `git ls-remote` call |
 | `KANON_GIT_RETRY_COUNT` | `3` | Maximum number of `git ls-remote` attempts |
 | `KANON_GIT_RETRY_DELAY` | `1` | Inter-attempt delay in seconds (read by doctor; not applied to the `git ls-remote` retry path, which delegates to `git_runner.run_git_ls_remote` and uses immediate retries with no time-based delay) |
-| `KANON_HOME` | `~/.kanon` | Shared kanon home (store + caches); cache lives under `${KANON_HOME}/cache`. Resolves from the `--home` / `--store-dir` flag, then this env var, then the `~/.kanon` default |
+| `KANON_HOME` | `~/.kanon-home` | Shared kanon home (store + caches); cache lives under `${KANON_HOME}/cache`. Resolves from the `--home` / `--store-dir` flag, then this env var, then the `~/.kanon-home` default |
 | `KANON_COMPLETION_ERRORS_REPORT_LIMIT` | `5` | Maximum number of recent completion-error log lines to display in subcheck 7 |
 | `KANON_CACHE_PRUNE_AGE_DAYS` | `30` | Files older than this many days (by atime) are removed by `--prune-cache` (subcheck 10) |
 | `KANON_DOCTOR_STALE_LOCK_SCAN_MAX_DEPTH` | `4` | Maximum directory depth for the stale install-lock scan in `--prune-cache` (subcheck 10) |