kanon-cli 3.1.0__tar.gz → 3.2.0__tar.gz

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/CHANGELOG.md

@@ -2,8 +2,136 @@
 
 
 
+## v3.2.0 (2026-07-13)
+
+### 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))
+
+
+## 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)
+
+Two defects found during QA of 3.1.0 against the namespaced/bare catalog.
+
+outdated (closes #85): _normalize_tag_revision_to_constraint only normalised a
+bare refs/tags/<pep440> to ==<pep440>; for a namespaced refs/tags/<path>/<pep440>
+it tried to parse the whole remainder as a Version, failed, and left the ref
+unchanged, so _resolve_constraint_from_tags raised "invalid version constraint".
+It now rewrites only the terminal version component while preserving the
+namespace path, so kanon outdated works for the default exact-tag add of both
+namespaced and bare entries.
+
+why (closes #86): when several sources resolve from the same repo URL at
+different commits (now a supported config), the ambiguity message printed N
+identical "source URL: <url>" tokens, so the operator could not disambiguate.
+_identity_token now returns the source alias (its derive_source_name identity)
+for a URL match on a source node, labelled "source name" -- the tokens are
+distinct and round-trip through the existing source-name grammar
+(kanon why <alias>). Project URL matches are unchanged.
+
+Adds unit + integration coverage for both (namespaced/bare exact-tag outdated;
+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)
 
+### Chore
+
+* chore(release): 3.1.0 ([`e62453e`](https://github.com/caylent-solutions/kanon/commit/e62453e4afa86dca403eef43f71b5ceb5e0a115b))
+
 ### Feature
 
 * feat: resolve catalog entries by tag namespace and accept bare project revisions #83
@@ -58,6 +186,12 @@ PEP 440 tag (refs/tags/<pep440>) for single-purpose repos, for both
   CLAUDE_MARKETPLACES_DIR header.
 - Tests, docs, and the kanon-add help snapshot updated. ([`7ed332c`](https://github.com/caylent-solutions/kanon/commit/7ed332c859e69cfd6635035a05c15c03339fdcd1))
 
+### Unknown
+
+* Merge pull request #84 from caylent-solutions/release-3.1.0
+
+Release 3.1.0 ([`fddb0aa`](https://github.com/caylent-solutions/kanon/commit/fddb0aa2ab847ffcf4857384d7e8b40504d1bf91))
+
 
 ## v3.0.0 (2026-06-26)
 

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.1.0
+Version: 3.2.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
@@ -183,7 +183,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`.
 
 ---
@@ -216,7 +216,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 +572,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 +587,12 @@ 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 outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -795,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
@@ -900,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:
 
@@ -909,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/

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/README.md

@@ -161,7 +161,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`.
 
 ---
@@ -194,7 +194,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 +550,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 +565,12 @@ 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 outdated
 
 Compares each source in `.kanon` against the catalog and emits a table of
@@ -773,9 +781,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 +886,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 +895,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/

{kanon_cli-3.1.0 → kanon_cli-3.2.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.0 → kanon_cli-3.2.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.0 → kanon_cli-3.2.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.0 → kanon_cli-3.2.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) |

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/cli-reference.md

@@ -14,7 +14,7 @@ are registered once via `kanon_cli.core.cli_args` so every parser exposes them.
 | `--quiet` / `--verbose` | -- | normal | Logging verbosity. Mutually exclusive. |
 | `--no-color` | `NO_COLOR` | auto | Disable ANSI color. Any non-empty `NO_COLOR` also disables color. |
 | `--no-update-check` | `KANON_SKIP_UPDATE_CHECK` | off | Skip the best-effort PyPI "update available" check. The flag is equivalent to setting `KANON_SKIP_UPDATE_CHECK=1`. |
-| `--home` / `--store-dir <path>` | `KANON_HOME` | `~/.kanon` | Shared kanon home root (content-addressed store plus caches). `--store-dir` is an accepted alias of `--home`. Precedence: flag > `KANON_HOME` env > `~/.kanon`. |
+| `--home` / `--store-dir <path>` | `KANON_HOME` | `~/.kanon-home` | Shared kanon home root (content-addressed store plus caches). `--store-dir` is an accepted alias of `--home`. Precedence: flag > `KANON_HOME` env > `~/.kanon-home`. |
 
 ## Shared Argument Factories
 
@@ -66,7 +66,7 @@ completion variables), see [docs/configuration.md](configuration.md).
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `KANON_CATALOG_SOURCES` | Remote catalog source(s) as `<git_url>@<ref>`, one entry per line. Sets the default for every command that accepts `--catalog-source`; the resolving commands require exactly one entry unless `--catalog-source` is passed. | (none) |
-| `KANON_HOME` | Shared kanon home root (store plus caches). Overridden by the `--home` / `--store-dir` flag. | `~/.kanon` |
+| `KANON_HOME` | Shared kanon home root (store plus caches). Overridden by the `--home` / `--store-dir` flag. | `~/.kanon-home` |
 | `KANON_SKIP_UPDATE_CHECK` | Set to `1` to skip the PyPI update-available check (same effect as `--no-update-check`). | (unset) |
 | `KANON_OUTDATED_FORMAT` | Default output format for `kanon outdated` (`table` or `json`). Overridden by `--format`. | `table` |
 | `KANON_OUTDATED_JSON_INDENT` | JSON indentation (number of spaces) used by `kanon outdated --format json`. | `2` |

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/configuration.md

@@ -380,7 +380,7 @@ chain.
 3. Default derived from `--kanon-file`: `./.kanon` becomes
    `./.kanon.lock`; `./alt.kanon` becomes `./alt.kanon.lock`.
 
-**`KANON_HOME`** (default: `~/.kanon`) -- Single root directory that
+**`KANON_HOME`** (default: `~/.kanon-home`) -- Single root directory that
 subsumes the former per-user cache-dir override and the former
 per-workspace artifact-dir override. The cache subtree lives at
 `${KANON_HOME}/cache/` and the store subtree at `${KANON_HOME}/store/`.
@@ -393,7 +393,7 @@ to cache files. See
 
 1. `--home` / `--store-dir <path>` global CLI flag (when supplied).
 2. `KANON_HOME` environment variable (when non-empty).
-3. `~/.kanon` -- default when the env var is unset and no flag is given.
+3. `~/.kanon-home` -- default when the env var is unset and no flag is given.
 
 The `--home` (alias `--store-dir`) flag is a global option accepted on
 every command; when supplied it overrides `KANON_HOME` for that

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/doctor.md

@@ -340,7 +340,7 @@ callback failures. These errors are non-blocking at the shell but are surfaced
 here so operators can diagnose completion failures.
 
 This check always runs. The cache directory resolves from `KANON_HOME` (the
-`--home` / `--store-dir` flag, then the env var, then the `~/.kanon` default).
+`--home` / `--store-dir` flag, then the env var, then the `~/.kanon-home` default).
 This subcheck emits only the stderr finding below; it does not print an `[ok]`
 summary line.
 

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/how-it-works.md

@@ -64,7 +64,7 @@ The command performs these steps:
    - Calls `kanon_cli.repo.repo_sync(source_dir)` -- aborts immediately on `RepoCommandError`
 5. **Aggregate symlinks** -- For each `.kanon-data/sources/<name>/.packages/*`, creates a symlink in `.packages/`
 6. **Collision detection** -- If two sources produce the same package name, fails fast with error identifying both sources
-7. **Update `.gitignore`** -- Ensures `.packages/` and `.kanon-data/` entries are present
+7. **Conditional store `.gitignore` safety net** -- Only when the shared `KANON_HOME` store sits inside a git working tree, writes `<KANON_HOME>/store/.gitignore` containing `*` so the fetched-artifact cache is never committed. When the store is not inside a git repo (the default `~/.kanon-home`), no `.gitignore` is written
 8. **Post-sync marketplace install** -- If any source sets `KANON_SOURCE_<alias>_MARKETPLACE=true`: locates the `claude` binary, discovers marketplace entries and plugins, registers marketplaces, and installs plugins via the Claude Code CLI
 
 ## Clean Lifecycle

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/installation.md

@@ -66,13 +66,17 @@ one top-level source while preserving every other lockfile entry, pass
 store, content-addressed and deduped across projects:
 
 - The store root resolves with precedence `--home` / `--store-dir`
-  flag > `KANON_HOME` environment variable > the default `~/.kanon`.
+  flag > `KANON_HOME` environment variable > the default `~/.kanon-home`.
 - The store directory is created if absent. If it cannot be created or is
   not writable, `kanon install` exits non-zero with an actionable
   message naming the path and the `KANON_HOME` variable -- there is no
   silent fallback.
 - `kanon clean` resolves the same store root, so it removes exactly what
   `kanon install` wrote.
+- The default store root is `~/.kanon-home`. Earlier versions defaulted to
+  `~/.kanon`, which collided with a project `.kanon` file when running kanon
+  from your home directory. A leftover `~/.kanon` directory from an older
+  install is unused and safe to delete (`rm -rf ~/.kanon`).
 
 The legacy per-project `.packages/` / `.kanon-data/` locations and their
 `KANON_WORKSPACE_DIR` / `KANON_CACHE_DIR` environment variables were

{kanon_cli-3.1.0 → kanon_cli-3.2.0}/docs/integration-testing.md

@@ -129,9 +129,10 @@ mkdir -p "${KANON_TEST_ROOT}"
 In kanon 3.0.0 the install artifacts no longer live next to `.kanon`. All
 fetched data is content-addressed under a **shared store** rooted at
 `KANON_HOME` (precedence: `--home`/`--store-dir` flag > `KANON_HOME` env >
-`~/.kanon` default). A successful `kanon install` writes only `.kanon.lock`
-into the project directory; the `.packages/`, `.kanon-data/sources/<name>/`,
-and store-level `.gitignore` artifacts are created under `<KANON_HOME>/store/`.
+`~/.kanon-home` default). A successful `kanon install` writes only `.kanon.lock`
+into the project directory; the `.packages/` and `.kanon-data/sources/<name>/`
+artifacts are created under `<KANON_HOME>/store/` (a store-level `.gitignore`
+containing `*` is written there only when the store sits inside a git repo).
 The removed per-project location variables (`KANON_WORKSPACE_DIR`,
 `KANON_CACHE_DIR`) are subsumed by this single store.
 
@@ -633,7 +634,7 @@ kanon install .kanon
 - Directory `${KANON_HOME}/store/.packages/` exists
 - `${KANON_HOME}/store/.packages/pkg-alpha` is a symlink
 - Symlink target path contains `${KANON_HOME}/store/.kanon-data/sources/primary/.packages/pkg-alpha`
-- `${KANON_HOME}/store/.gitignore` exists and contains both the `.packages/` and `.kanon-data/` lines
+- `${KANON_HOME}/store/.gitignore` is NOT created (the throwaway store is not inside a git repo; the safety-net `.gitignore` containing `*` is written only when the store sits inside a git working tree)
 
 **Clean:**
 
@@ -3519,16 +3520,16 @@ set -e
 
 **Pass criteria:** Exit code non-zero; stderr names the colliding package and both source names.
 
-### PK-13: store `.gitignore` promise -- `.packages/` and `.kanon-data/` lines added
+### PK-13: no store `.gitignore` for a non-git store
 
 ```bash
 pk_run pk13 "main"
-grep -q "^.packages/$" ${KANON_HOME}/store/.gitignore && grep -q "^.kanon-data/$" ${KANON_HOME}/store/.gitignore && echo "PASS: both lines present"
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: no .gitignore for non-git store"
 kanon clean .kanon
-grep -q "^.packages/$" ${KANON_HOME}/store/.gitignore && echo "PASS: clean preserved .gitignore lines"
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: still no .gitignore after clean"
 ```
 
-**Pass criteria:** Both `.packages/` and `.kanon-data/` lines added to `${KANON_HOME}/store/.gitignore` by install; lines remain after clean.
+**Pass criteria:** No `.gitignore` is written under `${KANON_HOME}/store/` (the throwaway store is not inside a git repo); none appears after clean. The safety-net `.gitignore` containing `*` is written only when the store sits inside a git working tree.
 
 ### Cleanup
 
@@ -5474,12 +5475,12 @@ KANON_SOURCE_a_NAME=a
 KANON_SOURCE_a_GITBASE=https://example.com
 KANONEOF
 kanon install
-grep -q "^.packages/$" ${KANON_HOME}/store/.gitignore || (echo "FAIL: install did not add"; exit 1)
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: no .gitignore for non-git store"
 kanon clean
-grep -q "^.packages/$" ${KANON_HOME}/store/.gitignore && grep -q "^.kanon-data/$" ${KANON_HOME}/store/.gitignore && echo "PASS: clean preserved both lines"
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: still no .gitignore after clean"
 ```
 
-**Pass criteria:** Both `.gitignore` lines added by install remain after clean.
+**Pass criteria:** No `.gitignore` is written under `${KANON_HOME}/store/` (non-git store); none appears after clean.
 
 ### TC-clean-03: `clean --orphans` prunes a removed source's marketplace
 
@@ -5649,11 +5650,11 @@ KANON_SOURCE_bravo_GITBASE=https://example.com
 KANONEOF
 kanon install .kanon
 test -L ${KANON_HOME}/store/.packages/pkg-alpha && test -L ${KANON_HOME}/store/.packages/pkg-bravo && echo "PASS: both"
-grep -q "^.packages/$" ${KANON_HOME}/store/.gitignore && grep -q "^.kanon-data/$" ${KANON_HOME}/store/.gitignore && echo "PASS: gitignore"
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: no .gitignore for non-git store"
 kanon clean .kanon
 ```
 
-**Pass criteria:** Both packages aggregated; `.gitignore` updated.
+**Pass criteria:** Both packages aggregated; no `.gitignore` is written (non-git store).
 
 ### UJ-04: `GITBASE` env override (`docs/pipeline-integration.md`)
 
@@ -6011,7 +6012,7 @@ kanon --home "${NS05_HOME}" clean .kanon
 ```
 
 **Pass criteria:** Exit code 0. The store is created under the explicit `--home`
-path (flag precedence: `--home`/`--store-dir` > `KANON_HOME` > `~/.kanon`), not
+path (flag precedence: `--home`/`--store-dir` > `KANON_HOME` > `~/.kanon-home`), not
 under the exported `KANON_HOME`. `--store-dir` is an accepted alias for `--home`.
 
 ### NS-06: `--no-update-check` suppresses the PyPI update check
@@ -6050,11 +6051,10 @@ directory, so the checks below operate from the store base:
 cd "${KANON_HOME}/store"
 ```
 
-### 16.1 .gitignore contents
+### 16.1 no store .gitignore for a non-git store
 
 ```bash
-grep -q "^\.packages/$" ${KANON_HOME}/store/.gitignore && echo "PASS: .packages/ in .gitignore" || echo "FAIL"
-grep -q "^\.kanon-data/$" ${KANON_HOME}/store/.gitignore && echo "PASS: .kanon-data/ in .gitignore" || echo "FAIL"
+test ! -e ${KANON_HOME}/store/.gitignore && echo "PASS: no .gitignore for non-git store" || echo "FAIL: unexpected .gitignore"
 ```
 
 ### 16.2 .packages/ contains symlinks
@@ -6338,7 +6338,7 @@ After running every scenario from §2 through §28, populate this spreadsheet-st
 | 162 | PK-10         | non-marketplace                    | linkfile + PEP 440                                     |        |      |         |       |
 | 163 | PK-11         | non-marketplace                    | multi-source PEP 440 mix                               |        |      |         |       |
 | 164 | PK-12         | non-marketplace                    | collision PEP 440                                      |        |      |         |       |
-| 165 | PK-13         | non-marketplace                    | .gitignore promise                                     |        |      |         |       |
+| 165 | PK-13         | non-marketplace                    | no store .gitignore (non-git store)                    |        |      |         |       |
 | 166 | RP-init-01    | repo-init                          | bare init                                              |        |      |         |       |
 | 167 | RP-init-02    | repo-init                          | --manifest-url long form                               |        |      |         |       |
 | 168 | RP-init-03    | repo-init                          | --manifest-name=alt.xml                                |        |      |         |       |