docs(skill): recommend install instead of plan and update

.agents/skills/kitup-release/SKILL.md

@@ -38,13 +38,14 @@ git push origin vX.Y.Z
 Release prep must keep these in sync:
 
 - `ts/package.json`
+- `python/pyproject.toml`
 - `rust/Cargo.toml`
 - `rust/Cargo.lock`
 - `examples/rust/Cargo.lock`
 - `go-cobra/go.mod`
 
 ## Automation
 
-The root `vX.Y.Z` tag triggers `.github/workflows/release.yml`. The workflow runs `make check`, verifies package versions, publishes npm and crates.io packages, creates `go/vX.Y.Z` and `go-cobra/vX.Y.Z`, creates GitHub Release notes, and runs `scripts/smoke-release.sh X.Y.Z`.
+The root `vX.Y.Z` tag triggers `.github/workflows/release.yml`. The workflow runs `make check`, verifies package versions, publishes npm, PyPI, and crates.io packages, creates `go/vX.Y.Z` and `go-cobra/vX.Y.Z`, creates GitHub Release notes, and runs `scripts/smoke-release.sh X.Y.Z`.
 
 If a registry already accepted a version, do not delete and recreate tags without an explicit recovery plan.

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@
 ## Scope Check
 
 - [ ] Stays within the v0.1 bundled-skill installer boundary.
-- [ ] Does not add marketplace, registry, remote install, script execution, GUI, MCP server, or agent runtime behavior.
+- [ ] Does not add marketplace, registry, private remote install, script execution, GUI, MCP server, or agent runtime behavior.
 - [ ] Updates golden cases for observable installer behavior changes.
 - [ ] Regenerates host constants after `spec/hosts.json` changes.
 

AGENTS.md

@@ -44,7 +44,7 @@ Use the live repository state, not memory or aspiration.
 - `spec/hosts.json` is the host adapter database.
 - `spec/*.schema.json` defines accepted shared data shape.
 - `testdata/cases/*.json` defines cross-language behavior.
-- Generated host constants in `ts/`, `go/`, and `rust/` come from `spec/hosts.json`; never edit them by hand.
+- Generated host constants in `ts/`, `go/`, `rust/`, and `python/` come from `spec/hosts.json`; never edit them by hand.
 - `scripts/sync-hosts.mjs` refreshes and checks generated host constants.
 - `scripts/check.mjs` is the current parity gate.
 - `docs/host-adapter-contract.md` explains host adapter semantics.
@@ -99,15 +99,15 @@ Ownership is controlled by `.kitup.json`:
 
 Conflict is the safe default. `force` and `adopt` must stay explicit, tested, and narrow.
 
-Content hashes must be deterministic across TypeScript, Go, and Rust. Hash bundled skill files by sorted relative path and bytes, excluding `.kitup.json` and transient files.
+Content hashes must be deterministic across TypeScript, Go, Rust, and Python. Hash bundled skill files by sorted relative path and bytes, excluding `.kitup.json` and transient files.
 
 Reports are API contracts. Return structured `installed`, `updated`, `skipped`, `conflicts`, and `errors` data instead of relying on logs.
 
 Skill bundles are directory trees. `SKILL.md` must live at the bundle root, but references, scripts, assets, and other regular files are part of the same bundle and must be validated, hashed, and copied as a tree.
 
 ## Multi-Language Parity
 
-TypeScript, Go, and Rust should be native SDKs that consume the same shared spec and fixtures.
+TypeScript, Go, Rust, and Python should be native SDKs that consume the same shared spec and fixtures.
 
 Do not replace this with a single binary core, cross-language FFI, shelling out to another runtime, or generated behavior unless the project direction is explicitly changed.
 

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Keep changes inside the v0.1 boundary:
 - copy, update, and uninstall kitup-owned installs
 - preserve `.kitup.json` ownership safety
 - return structured reports
-- keep TypeScript, Go, and Rust behavior aligned through golden cases
+- keep TypeScript, Go, Rust, and Python behavior aligned through golden cases
 
 Do not add marketplace, registry, private remote install, custom provider, script execution, MCP server, GUI, or agent runtime behavior unless the product boundary changes first.
 
@@ -39,15 +39,15 @@ scripts/check.mjs        spec, fixture, and SDK parity validation
 scripts/sync-hosts.mjs   generated host constants
 ```
 
-TypeScript, Go, and Rust SDKs live in `ts/`, `go/`, and `rust/`.
+TypeScript, Go, Rust, and Python SDKs live in `ts/`, `go/`, `rust/`, and `python/`.
 
 ## Common Commands
 
 ```bash
 make generate        # refresh generated host constants
 make generate-check  # verify generated host constants are current
 make check           # full parity and example gate
-make fmt             # format TypeScript, Go, and Rust files
+make fmt             # format TypeScript, Go, Rust, and Python files
 make clean           # remove local build outputs
 ```
 
@@ -59,7 +59,7 @@ Run the full parity gate before opening a pull request:
 make check
 ```
 
-This validates the shared spec, fixtures, generated host constants, standalone Go modules, TypeScript, Go, Rust, and examples.
+This validates the shared spec, fixtures, generated host constants, standalone Go modules, TypeScript, Go, Rust, Python, and examples.
 
 ## Host Adapter Changes
 
@@ -72,6 +72,7 @@ Host support is data-first.
   - `ts/src/hosts.generated.ts`
   - `go/hosts_gen.go`
   - `rust/src/hosts_generated.rs`
+  - `python/src/kitup/_hosts_generated.py`
 
 ## SDK Behavior Changes
 

README.md

@@ -52,6 +52,10 @@ Your CLI owns the command name and framework shell. `kitup` owns the standard in
 host detection, safe selection policy, summary text, confirmation, workflow exit classification, target paths,
 bundle validation, copy/update semantics, metadata, and conflicts.
 
+The recommended user-facing command is `skill install`. Use `--dry-run` to preview writes. Do not add `plan`,
+`update`, or `upgrade` subcommands; another install updates kitup-owned copies. Optional `status` and `uninstall`
+commands call the primitive APIs. Only the Go Cobra adapter ships those commands.
+
 ### TypeScript
 
 Install:
@@ -231,11 +235,14 @@ from kitup import resources_bundle
 bundle = resources_bundle(files("mycli.skills") / "mycli")
 ```
 
-For non-interactive or embedding scenarios, call `install_bundled_skill`, `plan_bundled_skill`, `update_bundled_skill`, `status_bundled_skill`, `read_installed_metadata`, or `uninstall_bundled_skill` directly.
+For non-interactive or embedding scenarios, call `install_bundled_skill`, `status_bundled_skill`,
+`read_installed_metadata`, or `uninstall_bundled_skill` directly. `plan_bundled_skill` is dry-run install;
+`update_bundled_skill` is install again.
 
 ## Docs
 
 - [API](docs/API.md)
+- [Architecture](docs/architecture.mmd)
 - [Contributing](CONTRIBUTING.md)
 - [Host adapter contract](docs/host-adapter-contract.md)
 - [Release](docs/RELEASE.md)

docs/API.md

@@ -437,11 +437,14 @@ Recommended CLI behavior:
 
 ```bash
 mycli skill install
+mycli skill install --dry-run
 mycli skill install --scope user --agent codex
 mycli skill install --scope project --agent codex --agent claude-code
 mycli skill install --scope user --agent codex --force
 ```
 
+Do not expose `plan`, `update`, or `upgrade` as separate commands. `planBundledSkill` / `updateBundledSkill` are the same install path: `--dry-run` plans, and another install updates kitup-owned copies. Optional `status` and `uninstall` commands call the primitive APIs; only the Go Cobra adapter ships those commands.
+
 The lower-level selection resolver remains available for custom shells. It returns one of:
 
 - `install`: proceed to plan and confirmation with `selectedHostIds`
@@ -481,6 +484,6 @@ Uninstall reports include:
 
 TypeScript returns typed report objects. Go exposes `InstallReport`, `UninstallReport`, `TargetResult`, `TargetStatus`, and `ReportError`. Rust exposes `InstallReport`, `UninstallReport`, `TargetResult`, `TargetStatus`, and `ReportError`.
 
-The serialized JSON report shape is the same across TypeScript, Go, and Rust. `installed`, `updated`, and `removed` contain target results. `skipped` and `conflicts` contain target results plus `reason`.
+The serialized JSON report shape is the same across TypeScript, Go, Rust, and Python. `installed`, `updated`, and `removed` contain target results. `skipped` and `conflicts` contain target results plus `reason`.
 
 Conflict is the safe default. A target directory without matching `.kitup.json` ownership metadata is reported as a conflict, not overwritten unless `force` / `--force` is explicit.

docs/vision.md

@@ -115,7 +115,7 @@ Most host support is path data. Put it in a shared host adapter database. Keep t
 
 ### Native over clever
 
-TypeScript, Go, and Rust users should get native SDKs. Avoid forcing a Go CLI to shell out to Node, or a Rust CLI to ship a JS runtime.
+TypeScript, Go, Rust, and Python users should get native SDKs. Avoid forcing a Go CLI to shell out to Node, or a Rust CLI to ship a JS runtime.
 
 ### Copy over symlink
 

skills/kitup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: kitup
-description: Use when integrating kitup into a CLI that ships bundled Agent Skills and needs to install, update, plan, or uninstall those skills across local agent hosts.
+description: Use when integrating the kitup SDK into a CLI that ships a bundled Agent Skill and needs to install it on local agent hosts. Also use when wiring install flags, optional status or uninstall, or the Go Cobra adapter.
 ---
 
 # Kitup
 
-Use kitup as a producer-side SDK. The embedding CLI owns the bundled skill; kitup owns host resolution, skill validation, copy/update/uninstall behavior, `.kitup.json` metadata, conflict safety, and structured reports.
+Use kitup as a producer-side SDK. The embedding CLI owns the bundled skill and command names. kitup owns host resolution, skill validation, copy/update/uninstall behavior, `.kitup.json` metadata, conflict safety, and structured reports.
 
 Call the SDK with:
 
@@ -14,4 +14,25 @@ Call the SDK with:
 - `scope`: `user` or `project`
 - `agents`: explicit host ids, `auto`, or all supported hosts
 
-Prefer `plan` before install when showing users what will change. Treat conflicts as stop conditions unless the SDK has explicit tested support for the desired override.
+## CLI surface
+
+Recommended user-facing command:
+
+```bash
+mycli skill install
+mycli skill install --dry-run
+```
+
+Standard install flags: `--scope`, repeatable `--agent`, `--dry-run`, `--yes` / `-y`, `--force`.
+
+Do not add `plan`, `update`, or `upgrade` subcommands. `--dry-run` is the plan. Re-running install updates kitup-owned copies of the same `appId`. `planBundledSkill` and `updateBundledSkill` are that same install path, not extra commands.
+
+Optional `status` and `uninstall` commands call `statusBundledSkill` and `uninstallBundledSkill`. Uninstall writes immediately; require `--yes` when stdin is not a TTY, and confirm in TTY mode. There is no uninstall force mode. Only the Go Cobra adapter ships these commands; other languages wire their own shell.
+
+## Wiring
+
+For user-facing install, parse flags with `parseInstallFlags` and call `runBundledSkillInstall` with `promptScope: true`. Set `stdinTTY` from the process terminal. Map exits with `installFlagError` and `installWorkflowError`.
+
+For scripts or tests that already know scope and agents, call `installBundledSkill` directly.
+
+Treat conflicts as stop conditions unless the caller passed explicit `--force`.