Metadata-Version: 2.4
Name: kinnoo
Version: 0.7.0
Summary: Kinnoo agent CLI and scaffolding tools
Author-email: Jerry Chen <jerryschen@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jerryjliu/kinnoo
Project-URL: Documentation, https://github.com/jerryjliu/kinnoo/tree/master/docs
Project-URL: Repository, https://github.com/jerryjliu/kinnoo
Project-URL: Issues, https://github.com/jerryjliu/kinnoo/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: cryptography>=42.0
Dynamic: license-file

# README

## Kinnoo is a developer platform for sharing agents.

## Packaging format

- `kinnoo pack` creates `.kno` artifacts as ZIP archives.
- `kinnoo install` expects `.kno` files in this ZIP-based format.

## OpenClaw Bridge Deprecation and Migration (Feature85)

Bridge-era OpenClaw features (feature62-feature67) are deprecated in favor of the Phase 7 CLI-wrapper model (feature76-feature84).

Migration command map:

- init wrapper: `kinnoo init --framework openclaw <name>`
- import wrapper: `kinnoo import <workspace-dir>`
- install wrapper: `kinnoo install <archive.kno>`
- run wrapper: `kinnoo run <agent-dir> '<prompt>' [--thinking <level>] [--json]`
- logs wrapper: `kinnoo logs --daemon openclaw [--follow] [--json]`
- skill install wrapper: `kinnoo install <agent-name> --openclaw-skill <owner/skill-or-url>`
- skill search wrapper: `kinnoo search --openclaw-skill <query> [--json]`

Deprecated bridge path notes:

- `--experimental-openclaw-adapter` remains compatibility-only and should not be used for new workflows.
- ClawHub mirror-first bridge flows are superseded by direct OpenClaw CLI delegation wrappers.

## OpenClaw Delegated Install (Feature65, Deprecated Bridge Context)

Bridge-era delegated install behavior is retained for compatibility only.

`kinnoo install` routes manifests declaring `type: openclaw-skill` through a delegated OpenClaw CLI install path.

Behavior:

- Kinnoo trust checks still run first (integrity/signature checks, manifest validation, install summary diagnostics).
- After validation, Kinnoo runs OpenClaw prechecks and delegates dependency install using:
	- `openclaw skills install .`
- Minimum CLI version gate is configurable:
	- `kinnoo install <archive.kno> --openclaw-min-version 0.2.0`

Deterministic delegated failure categories:

- `openclaw_cli_missing`: OpenClaw CLI executable is missing from `PATH`.
- `openclaw_cli_version_unsupported`: detected OpenClaw CLI version is below required minimum.
- `openclaw_cli_delegated_nonzero_exit`: delegated OpenClaw command exited non-zero.

Install trace behavior:

- Delegated outcomes are written to `.kinnoo/install-trace.json` under the installed target directory.
- Trace includes delegated backend metadata, minimum version, invoked command, category, and decision outcome.

## Manifest optional metadata (Feature9)

`kinnoo.yaml` supports these optional fields:

- `description` (string)
- `author` (string)
- `license` (string)
- `env_vars` (list of non-empty strings)

Notes:

- Existing V1 manifests remain valid when these fields are omitted.
- If `env_vars` is present, each entry must be a non-empty string.

## env_vars security contract (Feature10)

When an agent declares `env_vars`, `kinnoo run` resolves values in this order:

1. current process environment
2. agent-local `.env` file
3. masked interactive prompt for unresolved names

Security invariants:

- Secret values must never be printed, logged, or persisted by Kinnoo runtime flows.
- User-facing diagnostics reference variable names only.

Safe troubleshooting guidance:

- Verify required variable names are declared in `kinnoo.yaml` under `env_vars`.
- Check whether each required name exists in your shell environment or agent-local `.env`.
- If prompted, provide the value interactively; do not paste or print secret values into logs.

## kinnoo inspect (Feature11)

`kinnoo inspect` reads manifest metadata from either an agent directory or a `.kno` archive.

Usage:

- `kinnoo inspect <agent-dir>`
- `kinnoo inspect <archive.kno>`

Examples:

- `kinnoo inspect ./my-agent`
- `kinnoo inspect ./my-agent.kno`

Output semantics:

- Output is human-readable formatted text (not a raw YAML dump).
- Missing optional fields are omitted (not shown as `None` or empty placeholders).
- `env_vars` are displayed as variable names only; values are never shown.

Directory guidance behavior:

- Missing `kinnoo.yaml`: prints guidance plus a minimal manifest example and exits non-zero.
- Missing `requirements.txt`: prints guidance and robust generation commands:
	- `pip install uv`
	- `uv export --format requirements-txt > requirements.txt`

Common failure cases:

- Missing target argument: `Usage: kinnoo inspect <target>`
- Invalid archive: archive is not a valid zip-based `.kno` file
- Invalid manifest: prints `Error: Manifest validation failed.` with validator field-level errors

## kinnoo run --preflight (Feature14)

`kinnoo run --preflight` performs readiness validation only and does not execute agent logic.

Usage:

- `kinnoo run <agent-dir> --preflight`
- `kinnoo run ./my-agent --preflight`

Checklist behavior:

- Preflight always prints a deterministic checklist with pass/fail lines.
- Checklist sections include runtime version, env vars, entrypoint, and dependencies.
- If every check passes, output includes `Ready to run`.
- If any check fails, output includes `Not ready to run` and a remediation summary.
- Preflight confirms that entrypoint execution is skipped in preflight mode.

Security contract:

- Preflight output is names-only for environment variables.
- Preflight may list unresolved env var names, but it never prints env var values.

## Trust Baseline (Feature15)

Feature15 adds trust-focused behavior to install/run/inspect/pack workflows.

Install-time transparency and consent:

- `kinnoo install` shows a summary before installation, including:
	- agent name and version,
	- runtime type,
	- dependency names,
	- env var names (never values).
- Install prompt:
	- `Continue with install? [y/N]:`
	- default is No when user presses enter.
- `--yes` / `-y`:
	- keeps summary output,
	- skips confirmation prompt for CI and unattended workflows.

Feature39 install permission disclosure and consent:

- when manifest `permissions` is declared, install summary includes a deterministic permissions section:
	- network
	- filesystem scope
	- shell
	- browser
	- env access (names only)
- interactive installs require explicit permission consent:
	- `This agent declares explicit permissions. Allow requested permissions? [y/N]:`
	- default is deny
- non-interactive installs must use explicit override:
	- `kinnoo install ... --yes --accept-permissions`
	- using `--yes` without `--accept-permissions` aborts safely with guidance

Feature40 unsigned publisher warning and confirmation:

- when archive integrity is verified (checksum present) but no signature metadata is present, install emits:
	- `Warning: UNVERIFIED PUBLISHER - no signature metadata found for this archive.`
- interactive installs require explicit confirmation:
	- `UNVERIFIED PUBLISHER: no signature metadata found. Continue? [y/N]:`
	- default is deny
- non-interactive installs must use explicit override:
	- `kinnoo install ... --yes --allow-unverified-publisher`
	- using `--yes` without `--allow-unverified-publisher` aborts safely with guidance

Feature72 lockfile frozen mode:

- `kinnoo install --frozen` enforces lockfile-only reproducibility checks before extraction.
- Frozen mode validates lockfile entry presence, pinned version, and archive checksum.
- When lockfile drift is detected, install fails with deterministic remediation guidance:
	- `Re-run install without --frozen to regenerate lockfile, then retry --frozen.`
- Successful frozen installs leave lockfile content unchanged.

Feature74 uninstall behavior:

- `kinnoo uninstall <agent-name>` always requires interactive confirmation before deleting files.
- Successful uninstall removes the target install directory and writes an uninstall trace event.
- If lockfile metadata exists, uninstall removes the matching agent entry and rewrites lockfile state.
- Missing target uninstall failures are deterministic and actionable:
	- `Installed agent '<name>' was not found ...`
	- verify install root configuration (`KINNOO_AGENT_INSTALL_ROOT`) before retrying.

Unverified source warning:

- If `<archive>.sha256` is missing, install prints:
	- `This agent is from an unverified source.`
- Without `--yes`, install asks:
	- `This agent is from an unverified source. Continue? (y/n):`
- If checksum sidecar exists, unverified warning is skipped.

Run trace logging:

- After `kinnoo run` completes (success or failure), Kinnoo writes:
	- `~/.kinnoo/logs/run.<TIMESTAMP>.log`
- Timestamp in filename and JSON is UTC-only.
- Trace log JSON fields are safe-only:
	- `timestamp`, `agent_name`, `agent-version`, `runtime_type`, `exit_code`
- Trace logs never include:
	- user input content,
	- env var values,
	- secret values,
	- stdout/stderr payloads.

Heuristic security sweep (`inspect` and `pack`):

- `kinnoo inspect <agent-dir>` includes a `Security sweep:` section.
- Clean scan output:
	- `Security sweep: no env var exposure patterns detected (heuristic)`
- Dirty scan output includes warning lines with file and line details.
- `kinnoo pack <agent-dir>` runs the same sweep and prints warnings as non-blocking output.
- Disclaimer always applies:
	- `(heuristic scan — may produce false positives; not a substitute for code review)`

Project-wide security invariant:

- No env var or secret values are ever printed, logged, or persisted by Kinnoo trust paths.
- Diagnostics and trust output are names-only for env vars.

## Publisher key generation (Feature40)

Use `kinnoo keygen` to generate an Ed25519 keypair for archive signing and publisher verification.

Usage:

- `kinnoo keygen`
- `kinnoo keygen --private-key ./keys/publisher-private.pem --public-key ./keys/publisher-public.pem`

Behavior:

- Writes deterministic default filenames in the current working directory when paths are not provided:
	- `kinnoo-ed25519-private.pem`
	- `kinnoo-ed25519-public.pem`
- Enforces secure permissions for generated keys:
	- private key: `0600`
	- public key: `0644`
- Prints a public-key SHA256 fingerprint summary for operator verification.

Security notes:

- Kinnoo never prints private key material in command output.
- Keep private keys out of source control and store them in a secure operator-controlled location.
- Public keys may be distributed for verification workflows.

## Archive Integrity (Feature16)

Feature16 adds checksum lifecycle behavior across pack/install/inspect/publish using sidecar files.

Checksum sidecar contract:

- Sidecar naming: `<archive>.kno.sha256` (sibling to archive).
- Sidecar content format: `<sha256>  <archive-filename>`.
- SHA256 digest is lowercase hex and computed from archive bytes.

Pack behavior:

- `kinnoo pack` writes checksum sidecar after archive creation.
- Pack output includes:
	- `[kinnoo pack] Checksum sidecar written: <path>`

Install behavior (`kinnoo install <file.kno>`):

- Sidecar present + checksum match:
	- install proceeds,
	- output includes `[kinnoo install] Archive checksum verified.`
- Sidecar present + mismatch:
	- install aborts with exact error:
	- `Archive integrity check failed — the file may be corrupted or tampered with`
- Sidecar missing:
	- warning-only path continues install,
	- output includes: `No checksum file found — archive integrity not verified`

Inspect behavior:

- `kinnoo inspect <archive.kno>` reads sidecar when valid and displays:
	- `- Checksum (SHA256): <digest>`

Publish behavior:

- `kinnoo publish <agent-name>` copies sidecar to registry when source sidecar exists.
- Publish output includes one of:
	- `Published checksum sidecar: <path>`
	- `Published checksum sidecar: (none found at source)`

## Project Publish Target Toggle

`kinnoo publish` supports a project-level toggle in `kinnoo-config.txt` at your project root.

Example:

```txt
publish_to_authenticated_registry=true
```

Behavior:

- `true`: publish attempts authenticated remote registry publish by requesting a token from
	`KINNOO_REGISTRY_URL/api/auth/token` using:
	- `REGISTRY_ADMIN_EMAIL` (as username)
	- `REGISTRY_ADMIN_PASSWORD`
	- `KINNOO_TENANT_SLUG` (or `global` if unset)
- `false`: publish keeps current behavior (local/scratch default unless `--remote` or registry URL config is already forcing remote).

## Feature68 CI Publish Reference Workflow

Kinnoo includes a reference workflow at `.github/workflows/kinnoo-publish.yml` for automation pipelines.

Pipeline stages:

- install dependencies
- preflight compatibility check (`kinnoo check`)
- pack archive (`kinnoo pack`)
- publish to remote registry (`kinnoo publish --remote`)

Required secrets/environment contract:

- `KINNOO_REGISTRY_URL`
- `KINNOO_REGISTRY_TOKEN`
- `KINNOO_TENANT_SLUG`

Strict-mode compatibility control:

- `KINNOO_CI_STRICT_MODE=1` enables strict publish flags in the reference workflow when strict mode is available.

Security notes:

- Never commit credentials into repository files or workflow YAML.
- Keep registry auth values in GitHub Actions Secrets only.
- The workflow uses fail-fast shell settings (`set -euo pipefail`) so errors terminate with deterministic non-zero exits.

Troubleshooting common CI failures:

- Missing secrets: ensure `KINNOO_REGISTRY_URL`, `KINNOO_REGISTRY_TOKEN`, and `KINNOO_TENANT_SLUG` are configured in repo Actions Secrets.
- Preflight failures: run `python3 src/kinnoo/cli.py check <agent-dir>` locally to reproduce manifest/runtime contract issues.
- Signing failures (if your pipeline enables signing): verify the private signing key path is available to the runner and referenced by your signing step.
- Publish failures: verify token scope and tenant mapping, then retry with explicit remote mode (`kinnoo publish --remote`) for deterministic behavior.

Strict rollout guidance:

- Start with `KINNOO_CI_STRICT_MODE=0` while validating signature coverage for all publish paths.
- Move to required gate mode by setting `KINNOO_CI_STRICT_MODE=1` and enforcing `publish --strict` in protected-branch workflows.
- In strict mode, unsigned artifacts fail closed and must be re-packed with `kinnoo pack --sign`.

## Feature69 kinnoo test command

Kinnoo includes a standardized declarative test runner for agent projects.

Canonical test file:

- `kinnoo.tests.yaml`

CLI usage:

- `kinnoo test ./my-agent`
- `kinnoo test ./my-agent --json`
- `kinnoo test ./my-agent --validate-only`

Minimal Python one-shot example:

```yaml
version: 1
tests:
	- id: smoke-oneshot
		name: one-shot response smoke test
		input: hello
		assertions:
			- contains: hello
		timeout_seconds: 5
		expected_exit_code: 0
```

JS/TS daemon-compatible example:

```yaml
version: 1
tests:
	- id: smoke-daemon
		name: daemon-compatible response smoke test
		input: ping
		assertions:
			- contains: pong
		timeout_seconds: 10
		expected_exit_code: 0
```

Notes:

- one-shot and daemon-compatible runtimes use the same assertion contract, so CI summaries stay consistent.
- prefer deterministic output assertions (`contains`, `equals`, `regex`) over broad semantic checks.

## Feature70 phase6 command matrix and provenance messaging

Phase 6 command matrix (high-signal operational commands):

- `kinnoo login`
- `kinnoo logout`
- `kinnoo list --remote`
- `kinnoo search <query> --remote`
- `kinnoo import --source clawhub <owner>/<slug>`
- `kinnoo sync clawhub`
- `kinnoo check <agent-dir>`
- `kinnoo test <agent-dir>`
- `kinnoo pack <agent-dir>`
- `kinnoo publish <agent-name> --remote`

ClawHub mirror attribution model:

- mirrored records are written under tenant slug `clawhub`
- source provenance stays explicit via source registry metadata and mirror attribution fields
- operators can verify that mirrored entries and local sync behavior reference the same `clawhub` tenant model

Phase 6 forward command references (consistency contract):

- strict trust mode: `kinnoo install --strict` and `kinnoo publish --strict`
- lockfile reproducibility: `kinnoo install --frozen`
- archive compare: `kinnoo diff <a.kno> <b.kno>`
- uninstall flow: `kinnoo uninstall <agent-name>`
- framework adapters: `kinnoo import --from langchain|langgraph|openai`

## Registry Login and Logout

`kinnoo login` and `kinnoo logout` manage local registry auth state for CLI registry workflows.

Usage:

- Interactive login:
	- `kinnoo login`
- Non-interactive login:
	- `kinnoo login --email user@example.com --password '<password>'`
- Logout:
	- `kinnoo logout`

Persistence and precedence:

- Successful login persists `registry_url`, `registry_token`, and `tenant_slug` in `~/.kinnoo/config.yaml`.
- Login resolves registry URL from (in order): `KINNOO_REGISTRY_URL`, existing config value, then default `https://registry.kinnoo.ai`.
- Tenant slug is resolved by the auth handshake and persisted from token claims; users do not need to pass `--tenant`.
- `kinnoo logout` clears persisted auth keys from `~/.kinnoo/config.yaml`.
- Environment variables remain highest precedence over file config:
	- `KINNOO_REGISTRY_URL`
	- `KINNOO_REGISTRY_TOKEN`
	- `KINNOO_TENANT_SLUG`
- After logout, remote registry operations requiring auth fail unless explicit env-var overrides are provided.
- `kinnoo list --remote` and `kinnoo search --remote` are fail-closed:
	- they require `KINNOO_REGISTRY_URL` (or a persisted `registry_url`),
	- they require token + tenant auth context,
	- they do not fall back to local mock storage.

Security notes:

- Kinnoo never prints tokens or passwords in CLI output.
- Prefer environment variables for CI/non-interactive auth flows.

Notes:

- `kinnoo publish --local` and `kinnoo publish --remote` still take precedence when explicitly provided.
- If the toggle is `true`, ensure `KINNOO_REGISTRY_URL`, `REGISTRY_ADMIN_EMAIL`, and `REGISTRY_ADMIN_PASSWORD` are set.

## Pack Size Reporting & Warnings (Feature17)

Feature17 adds package-footprint visibility across pack/inspect/list workflows.

Pack behavior:

- `kinnoo pack` prints final archive size after artifact creation:
	- `[kinnoo pack] Archive size: <human-readable>`
- If archive size is strictly greater than 100 MB, pack prints:
	- `Warning: archive is large (X MB). Consider whether all dependencies are necessary.`

Inspect behavior:

- `kinnoo inspect <archive.kno>` includes archive size metadata:
	- `- Archive Size: <human-readable>`

List behavior:

- `kinnoo list`, `kinnoo list --local`, and `kinnoo list --remote` include additive size visibility per row:
	- `| size: <human-readable>`
- Size formatting is shared across commands and uses stable units (`B`, `KB`, `MB`, `GB`).

## Asset Bundling Compatibility (Feature22)

Feature22 adds optional manifest-driven asset bundling via `assets`.

Compatibility guarantees:

- Agents that do not declare `assets` continue to use the same pack/install behavior as pre-Feature22 flows.
- `assets.paths` accepts file paths and directory paths relative to the agent root.
- Directory paths are bundled recursively; declaring a base folder includes nested files/subfolders.
- `assets.bundle: false` keeps asset metadata but skips asset payload inclusion in the archive.
- `assets.max_bundle_size_mb` overrides the default 100 MB warning threshold when provided.

## Mutable State Snapshots (Feature35)

Feature35 introduces `state_dirs` for mutable runtime state such as memory folders. This is intentionally separate from immutable `assets`.

Behavior summary:

- `assets` remain immutable packaged resources with existing bundle behavior.
- `state_dirs` are packed as mutable snapshots under `state_snapshots/<declared-state-dir>/...`.
- install restores snapshots back into each declared state root.

Structured `state_dirs` entries support exclude patterns:

```yaml
state_dirs:
	- path: memory
		exclude:
			- daily/*.md
			- secrets/*
```

Exclude and restore semantics:

- Excluded files are omitted during pack and therefore never restored.
- Non-excluded files remain part of the snapshot/restore flow.
- Install is warning-first and non-destructive when existing state is present.
- Use `kinnoo install ... --state-overwrite` for explicit deterministic replacement of existing state.

Compatibility guarantee:

- Agents without `state_dirs` keep legacy asset-only pack/install behavior unchanged.

## Input Safety Guard (Feature18)

Feature18 adds an input safety guard to `kinnoo run` before agent execution.

Guard behavior:

- The guard runs automatically for `kinnoo run <agent-dir> "<input>"` before entrypoint execution.
- It evaluates user input for common injection patterns and emits warnings to stderr.
- The guard is non-blocking by design:
	- in interactive terminals, users can acknowledge risk and proceed,
	- in non-interactive mode, execution aborts by default for safety.

Threat categories currently covered:

- SQL injection
- shell command injection
- path traversal
- SSRF
- XSS
- template injection

CLI override for automation:

- `--no-guard` disables the input safety check for trusted CI/automation pipelines.

Type-aware checking model:

- The guard supports typed checks (`text`, `string`, `file_path`, `url`, `id`) so threat-category evaluation can be narrowed by input semantics.
- This supports future parameterized input flags without changing the guard contract.

Architecture note:

- The guard is implemented behind an `InputGuard` Protocol and factory (`get_default_guard()`), enabling future replacement with a model-based or hybrid classifier while preserving runtime integration.

## JSON I/O Contract (Feature42)

Feature42 adds manifest-driven structured I/O support while keeping legacy text workflows unchanged.

Manifest contract:

- `inputs.type` can include `json` for structured request payloads.
- `outputs.type` can include `json` for structured response payloads.
- Text workflows remain additive-compatible: existing `text` agents and commands keep the same behavior.

Run command usage:

- Inline JSON: `kinnoo run <agent-dir> --json-input '{"task":"ping"}'`
- File JSON: `kinnoo run <agent-dir> --json-file ./payload.json`

Output contract enforcement:

- When `outputs.type` includes `json` for one-shot runtimes, stdout must be valid JSON.
- Invalid JSON output fails with parse-context diagnostics (line/column) without echoing secret values.

Inspect and preflight visibility:

- `kinnoo inspect` shows declared input/output types and JSON contract hints.
- Inspect metadata includes `Input Types`, `Output Types`, and `JSON Contract` lines when applicable.
- `kinnoo run <agent-dir> --preflight` prints an explicit manifest I/O contract line, including JSON-mode guidance.

## Feature33 manifest extensions for Node/OpenClaw

Feature33 adds optional manifest fields for Node.js-oriented agent metadata:

- `runtime.package_manager`: allowed values are `npm` or `pnpm`
- `channels`: list of non-empty strings
- `skills`: list of non-empty relative paths (no absolute paths or `..` traversal)
- `state_dirs`: list of non-empty relative paths (no absolute paths or `..` traversal)

OpenClaw-targeted behavior (`framework: openclaw`):

- `runtime.language` must be `nodejs`
- `runtime.type` must be `daemon`
- `runtime.package_manager` is required with value `npm` or `pnpm`
- `channels` must include `stdio`

Non-openclaw compatibility:

- Existing manifests that omit Feature33 fields remain valid.
- Non-openclaw manifests may include Feature33 fields in valid shape without OpenClaw-only validation failures.

## Mutable state snapshots (Feature35)

Feature35 defines `state_dirs` as mutable runtime state snapshots, which are distinct from immutable `assets`.

Semantics:

- `assets` are immutable packaged resources intended to be identical across installs.
- `state_dirs` are mutable warm-start runtime state that can change over time.
- During pack, `state_dirs` content is stored under `state_snapshots/<state-dir>/...` to keep state semantics separate from asset paths.

Exclusion support:

- Structured entries support per-directory excludes:

```yaml
state_dirs:
	- path: memory
		exclude:
			- daily/*.md
			- secrets/*
```

- Excluded files are omitted from snapshots and therefore are not restored on install.

Install restore and overwrite behavior:

- By default, install is warning-first and non-destructive when target state already exists.
- Existing state is preserved unless explicit overwrite is requested.
- Use `--state-overwrite` to replace existing state with snapshot content.

Backward compatibility:

- Agents without `state_dirs` preserve legacy asset-only pack/install behavior.

## Pack/Publish Refactor (Feature13)

Feature13 shifts command responsibilities to an archive-first source model and a mock-registry publish target.

### Pack (archive-first)

- `kinnoo pack <agent-dir>` writes by default to:
	- `~/.kinnoo/archive/<agent>/<version>/<agent>.kno`
- For tests and custom environments, archive root can be overridden with:
	- `KINNOO_ARCHIVE_ROOT`

### Publish (name-based source)

- `kinnoo publish <agent-name>`
- `kinnoo publish <agent-name> --local`

Behavior:

- Source artifact resolves from latest local archive version for `<agent-name>`.
- Target publishes to mock registry path:
	- `~/kinnoo-mock-registry-scratch/jerry/<agent>/<version>/<agent>.kno`
- If tagged target already exists, previous payload is preserved under:
	- `~/kinnoo-mock-registry-scratch/jerry/<agent>/untagged-<n>/`

### Install selectors

`kinnoo install` supports all of the following:

- `kinnoo install <name>` (latest from mock registry)
- `kinnoo install <name>==<version>` (exact version from mock registry)
- `kinnoo install <file-path/file.kno>` (backward-compatible direct archive install)

### List source modes

- `kinnoo list` (default local archive)
- `kinnoo list --local` (same as default)
- `kinnoo list --remote` (configured remote registry inventory; no local fallback)

### Search source modes

- `kinnoo search <query>` (default local archive)
- `kinnoo search --local <query>` (same as default)
- `kinnoo search --remote <query>` (configured remote registry inventory; no local fallback)

Search and list preserve consistent output shape (`name`, `latest`, `description`) and use case-insensitive matching for search name/description filtering.

### Migration notes from Feature12

- Old publish form:
	- `kinnoo publish <archive.kno>`
- New canonical publish form:
	- `kinnoo publish <agent-name>`

- Old registry docs centered on `~/.kinnoo/registry/` as primary source/target.
- Feature13 split:
	- source of truth for packaged artifacts: local archive (`~/.kinnoo/archive/...`)
	- publish target: mock registry (`~/kinnoo-mock-registry-scratch/jerry/...`)
