sshscript 4.0.1__tar.gz → 5.0.0__tar.gz

sshscript-5.0.0/AI_GUIDE.md

@@ -0,0 +1,58 @@
+# SSHScript for AI agents
+
+**Documentation contract: SSHScript 5.0.0; Python 3.11+.**
+
+Start with the [agent guide](skills/sshscript/references/agent-guide.md).
+It explains version checks, API selection, command results, input, deadlines,
+authentication and cleanup. Read only the task-relevant sections of the
+[canonical API guide](API_GUIDE.md) and [version policy](VERSIONING.md).
+
+The [SSHScript skill](skills/sshscript/SKILL.md) supplies a compact operating
+workflow. Its folder contains the supporting guide; copy the entire
+`skills/sshscript/` folder when installing it in an agent's skill directory.
+It teaches SSHScript usage, not development of SSHScript itself or a particular
+recipe library. Agents without skill support can read these Markdown files.
+
+## Share one URL
+
+The website entry is [SSHScript for AI Agents](https://iapyeh.github.io/sshscript/v3a/ai-agents/).
+After these files are published, users can give that URL and a task to an agent:
+
+> Read the SSHScript AI agent entry at
+> https://iapyeh.github.io/sshscript/v3a/ai-agents/ and follow its reading order.
+> Check the SSHScript version in my environment before selecting APIs. Help me
+> complete this task: [describe the task, target hosts and expected output].
+> If you cannot read a required document, report that limitation rather than
+> guessing its contents. Explain the proposed commands before execution and
+> stay within the operations I authorize.
+
+A URL supplies reference material for the current task. It does not install
+SSHScript, install a skill, grant execution permission, or guarantee persistent
+memory. An agent needs URL-reading tools, or the user must provide the files.
+
+## Maintain the source and website
+
+Maintain this entry, `skills/sshscript/SKILL.md`, and its reference guide in
+the designated `working_branch` checkout on branch `working_branch`.
+The landing page is maintained in `gh-pages/v3a/ai-agents/index.md` on branch
+`gh-pages`. The API guide remains authoritative for public behavior.
+
+From `working_branch`, synchronize the generated website guide, plain-text
+files and portable skill ZIP with:
+
+```sh
+python3 tools/sync_ai_docs.py ../gh-pages/v3a
+python3 tools/sync_ai_docs.py ../gh-pages/v3a --check
+```
+
+The ZIP includes the skill and its reference guide, plus snapshots of
+`API_GUIDE.md` and `VERSIONING.md` for offline use. These snapshots are generated
+from the source documents; do not edit the ZIP or generated website copies.
+The sync command checks the destination branch before writing. Website pages
+keep their Last Updated timestamp aligned with their mtime.
+
+When the execution contract changes, review the skill and guide, update their
+contract labels and the landing page, then regenerate the website assets.
+Validate links, skill structure, example behavior, source/ZIP equality and
+the rendered website. Source and website publishing are separate operations;
+copying files does not publish either of them.

{sshscript-4.0.1 → sshscript-5.0.0}/API_GUIDE.md

@@ -1,8 +1,8 @@
 # Recommended SSHScript API
 
 This is the canonical entry point for new code and AI-generated examples.
-**Current contract: 4.0.1**, Python 3.11+. Sections marked **4.0** require
-SSHScript 4.0.1; installing `sshscript==3.1.5` does not provide them.
+**Current contract: 5.0.0**, Python 3.11+. Sections marked **4.0** require
+SSHScript 4.0.2 or newer; installing `sshscript==3.1.5` does not provide them.
 Examples labelled 3.1.5 remain verified compatibility examples for that baseline.
 Pin the exact artifact version and record it with execution diagnostics when
 handing off automation. See [version policy and migration](VERSIONING.md).
@@ -29,9 +29,11 @@ identifiers and handoff reports are future work, not a current API guarantee.
 | Long-running program | **4.0:** `start(timeout=None)`, `stop()`, `wait()` |
 | Session-wide failure/output policy | **4.0:** `set(...)`, `get(...)`, or matching properties |
 
-## 3.1.5: one command, one retained result
+## One command, one retained result (4.0; compatible with 3.1.5)
 
-Install the baseline with `python -m pip install "sshscript==3.1.5"`.
+Install the current release with `python -m pip install "sshscript==5.0.0"`.
+For reproducing only the historical compatibility baseline, explicitly install
+`sshscript==3.1.5`; the 4.0 sections require the current release.
 An argv list is one command, not a batch. Shell-looking argument text stays data.
 
 <!-- example: {"id":"argv", "profile":"3.1.5", "stdout":"a; b\n"} -->
@@ -67,7 +69,7 @@ with closing(Session()) as local:
         print(f"failed: {error.returncode}")
 ```
 
-## 3.1.5: SSH and optional dollar syntax
+## SSH and optional dollar syntax (4.0; compatible with 3.1.5)
 
 Replace the example host with your configured host and verified known-host key.
 CI executes this block with a local SSH protocol fixture in place of the login;
@@ -86,6 +88,139 @@ with closing(Session()) as local:
         print(result.stdout)
 ```
 
+### Private-key paths and nested connections
+
+`parent.connect(..., pkey_path=path)` loads an RSA private key from the
+**calling parent Session's host**. A local Session reads the file on localhost;
+a Session connected to host1 reads it on host1 through SFTP before connecting
+to host2. `connect()` returns a child Session and leaves the parent on its
+original host. Calling the original local Session again therefore still reads
+the key on localhost.
+
+For example, `local.connect("host1", pkey_path="/local/key_rsa")` reads
+`/local/key_rsa` locally and returns `host1`. Then
+`host1.connect("host2", pkey_path="/remote/key_rsa")` reads `/remote/key_rsa`
+on host1. In `.spy`, an inner `with $.connect(...)` uses the outer scope's
+current Session as its parent.
+
+`key_filename=` is forwarded to Paramiko and reads from the local Python
+process's filesystem even for nested connections; it supports additional key
+formats. For an encrypted RSA key, use
+`pkey=parent.pkey(path, password=key_passphrase)` to retain the same host-based
+reading rule. Supplying both `pkey_path` and `pkey` raises `ValueError`.
+See the [agent guide's complete nested example](https://iapyeh.github.io/sshscript/v3a/ai-agents/guide/#ssh-connections-and-private-key-paths).
+
+<a id="host-key-sources-unreleased"></a>
+
+### Host-key sources (5.0)
+
+This section requires SSHScript 5.0.0 or newer.
+`known_hosts` selects the host-key trust source independently of `policy`:
+
+| Value | Sources, in order |
+| --- | --- |
+| `"parent"` (new default) | Only the calling Session's host |
+| `"local"` | Only the root localhost Session |
+| `"chain"` | Calling Session, then each ancestor through localhost |
+
+For localhost → host1 → host2 → host3, `host2.connect("host3",
+known_hosts="chain")` consults host2, host1, then localhost. The nearest source
+with a record for the resolved target hostname and port is authoritative.
+A matching key is accepted; a changed key is rejected even if a more distant
+source matches. Only absence of a target record permits continuing the chain.
+Different key algorithms do not permit falling back to another source.
+
+Each source reads its own `known_hosts_path`, or `~/.ssh/known_hosts` if unset.
+Remote files are read over SFTP as that Session's original SSH login account;
+SSH handshakes, user authentication and host-key verification still run in the
+local Python process. Neither sudo/su nor a nested connection changes the SFTP
+account. Remote `~/` paths refer to the login account's SFTP home; `~user` paths
+are unsupported. Relative remote paths use the SFTP working directory.
+
+```py
+local.set(known_hosts="chain")
+# After connecting to host1 and host2:
+host1.set(known_hosts_path="/home/ops/.ssh/known_hosts")
+host2.set(known_hosts_path="/etc/ssh/ssh_known_hosts")
+with host2.connect("deploy@host3", pkey_path="/home/ops/.ssh/host3_rsa") as host3:
+    result = host3.exec_command(["hostname"], check=True, command_timeout=10)
+```
+
+The strategy is inherited by future child Sessions; the path is host-specific
+and is **not inherited**. `known_hosts_path=None` restores the standard path.
+A `connect(known_hosts=...)` override affects only that connection; it does not
+change the parent setting or the child's inherited strategy. `set()`, `get()`
+and matching properties expose both settings. `known_hosts_path` accepts text
+paths and `PathLike[str]`; it is a Session setting, not a `connect()` keyword.
+
+`pkey_path` always reads only from the calling Session's host, including with
+`known_hosts="chain"`; private keys are never searched through ancestors.
+
+An absent trust file, permission failure, read failure, invalid UTF-8 or invalid
+entry raises an error; no distant source or permissive policy bypasses it.
+Empty files, comments, plain host-key entries (including comma-separated names)
+and hashed hostnames are supported. OpenSSH markers such as `@cert-authority`
+and `@revoked`, wildcard/negated host patterns and unsupported key types raise
+an error rather than being silently ignored. A source file is fully parsed
+before its records are used. Nonstandard ports use `[hostname]:port` records.
+
+When every selected source lacks the target, `policy` handles the unknown key.
+`AutoAddPolicy` accepts it into the new client's memory only; these trust files
+are read-only and are not automatically updated locally or remotely.
+
+**Migration from 4.0.2:** earlier releases always load localhost host keys. The new default
+`"parent"` makes nested host-key sources consistent with `pkey_path`. To retain
+the previous behavior, set `local.set(known_hosts="local")` before connecting.
+All strategies require a readable, valid file, including the default localhost
+path. Unlike 4.0.2, a missing local file is an error; create an empty
+file if the configured missing-key policy should handle unknown hosts.
+
+### Private keys readable only in a privileged console
+
+Remote `pkey()` and `pkey_path` use SFTP with the original SSH login account.
+Entering `sudo()` or `su()` does not change that identity, so even
+`$.pkey("/root/.ssh/id_rsa")` inside a root console can fail with a permission
+error. When authorized, read the file with a console command and construct
+the Paramiko key from its captured text:
+
+This manual example requires a real privileged console and SSH endpoints;
+it is excluded from credential-free executable examples.
+
+```py
+from contextlib import closing
+from io import StringIO
+import paramiko
+from sshscript import Session
+
+with closing(Session()) as local:
+    with local.connect("ops@host1.example.net", timeout=10,
+                       banner_timeout=10, auth_timeout=10) as host1:
+        with host1.sudo() as root:
+            key_result = root("cat /root/.ssh/id_rsa", check=True, command_timeout=10)
+            key = paramiko.RSAKey.from_private_key(StringIO(key_result.stdout))
+        with host1.connect("deploy@host2.example.net", pkey=key, timeout=10,
+                           banner_timeout=10, auth_timeout=10) as host2:
+            result = host2.exec_command(["hostname"], check=True, command_timeout=10)
+            print(result.stdout)
+```
+
+The example requires authorized sudo/SSH access and verified host keys.
+Configure output logging/display to keep private-key text out of logs before
+running the read; do not print or report `key_result` or its stdout. Key text
+also remains in console buffers. Use the matching Paramiko key class for
+other formats; encrypted RSA keys need `password=` on `from_private_key()`.
+An authorized `su()` console can supply the text in the same way.
+
+The console returned by `shell()`/`sudo()`/`su()`/`enter()` has no `connect()`
+method, so `$.connect()` is unavailable while a console is current in `.spy`.
+A retained Python Session can still call `connect()` during an active console;
+the connection uses its original SSH transport and does not inherit console
+privilege. The example leaves the console first and calls the retained
+`host1.connect(pkey=key)`, which needs no SFTP key read. See the
+[agent guide's `.spy` equivalent](https://iapyeh.github.io/sshscript/v3a/ai-agents/guide/#keys-readable-only-after-sudosu).
+
+### Optional dollar syntax
+
 Save dollar syntax as `.spy`, run with `sshscript file.spy`, and syntax-check
 without execution using `sshscript --check file.spy`.
 
@@ -99,7 +234,7 @@ print(result.stdout)
 
 ## 4.0: settings and managed jobs
 
-Use SSHScript 4.0.1 for the following examples. CLI `-v`, `--stderr`, and
+Use SSHScript 5.0.0 for the following examples. CLI `-v`, `--stderr`, and
 `--debug` override root defaults only for that execution. Child Sessions copy
 their parent's settings. `set()` validates before changing anything; `get()`
 returns a copy. Explicit command options override Session policy.
@@ -118,7 +253,7 @@ the settings dictionary at creation; the policy object itself is shared, so
 custom policies with mutable state must account for reuse. Changing the setting
 does not reconfigure existing connections.
 
-<!-- example: {"id":"settings", "profile":"4.0.1", "stdout":"True\n1\n"} -->
+<!-- example: {"id":"settings", "profile":"5.0.0", "stdout":"True\n1\n"} -->
 ```python
 from contextlib import closing
 import paramiko
@@ -140,7 +275,7 @@ semantics; do not combine it with `command_timeout`.
 For an indefinite command such as tcpdump, use `start(timeout=None)`. This safe
 local example uses a small Python process instead of capturing network traffic:
 
-<!-- example: {"id":"stop", "profile":"4.0.1", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stop", "profile":"5.0.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -179,7 +314,7 @@ legacy SSH behavior which appended a newline to strings: if a consumer
 needs a line, migrate `input=password` to `input=password + "\n"` explicitly.
 Published 3.1.5 still has the legacy SSH behavior.
 
-<!-- example: {"id":"exact-stdin", "profile":"4.0.1", "stdout":"'abc'\n'abc\\n'\n"} -->
+<!-- example: {"id":"exact-stdin", "profile":"5.0.0", "stdout":"'abc'\n'abc\\n'\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -248,7 +383,7 @@ or unpack exactly `stdout, stderr, exitcode`. This changes the released 3.1.5
 console contract: old `stdout, stderr = shell(command)` must be migrated.
 Shell calls accept command strings; argv execution belongs to Session.
 
-<!-- example: {"id":"shell-result", "profile":"4.0.1", "stdout":"first 0\n"} -->
+<!-- example: {"id":"shell-result", "profile":"5.0.0", "stdout":"first 0\n"} -->
 ```python
 from contextlib import closing
 from sshscript import Session
@@ -304,7 +439,7 @@ matching: `iter_stdout()` yields chunks, not packets or lines. Put `stop()` in
 `finally`, so condition matches, exceptions, and KeyboardInterrupt all trigger
 cleanup. This credential-free example uses a continuous Python process:
 
-<!-- example: {"id":"stream-condition", "profile":"4.0.1", "stdout":"cancelled confirmed\n"} -->
+<!-- example: {"id":"stream-condition", "profile":"5.0.0", "stdout":"cancelled confirmed\n"} -->
 ```python
 from contextlib import closing
 import sys
@@ -369,7 +504,7 @@ the current Bash console's channel, cwd, environment and identity. It does not
 launch through the underlying Session. Ordinary `console(command)` / `$command`
 still waits and returns `CommandResult`; no migration is needed for finite commands.
 
-<!-- example: {"id":"console-stream", "profile":"4.0.1", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
+<!-- example: {"id":"console-stream", "profile":"5.0.0", "stdout":"cancelled confirmed\nconsole-alive\n"} -->
 ```python
 from contextlib import closing
 import shlex
@@ -509,7 +644,7 @@ remains available for other authentication prompt formats.
 These transcripts require a real local account and its authentication policy;
 they are manual examples, separate from the credential-free CI examples above.
 Read passwords with `getpass` rather than storing them in the script. The new
-behavior requires 4.0.1 and does not apply to the installed 3.1.5 release.
+behavior requires 4.0.2 or newer and does not apply to the installed 3.1.5 release.
 
 Open a root console through sudo and allow up to 15 seconds for entry:
 

{sshscript-4.0.1 → sshscript-5.0.0}/CHANGELOG.md

@@ -3,6 +3,28 @@
 This project records user-visible changes here. Release artifacts and their
 provenance are available from the linked GitHub Release and PyPI pages.
 
+## 5.0.0 — 2026-10-10
+
+- Add `known_hosts="parent"` (new default), `"local"` and `"chain"` strategies.
+  Nested connections now use the calling host's trust file by default, matching
+  `pkey_path` ownership. Set `known_hosts="local"` for previous behavior.
+- Add per-Session `known_hosts_path` without path inheritance. Chain lookup uses
+  the nearest target record; changed keys and read/parse errors never fall back.
+  Authentication and verification still run locally; trust files are read-only.
+- Isolate connection-timeout tests from runner HOME and verify client cleanup.
+- Document host-key source selection, strict file errors and migration in the
+  API, website and portable AI agent skill.
+
+## 4.0.2 — 2026-10-09
+
+- Align the README, current installation commands, website title, navigation,
+  footer, and version metadata with the current 4.0 release.
+- Point general PyPI and GitHub Release links to current entry points; retain
+  explicitly labelled historical releases and existing documentation URLs.
+- Check current website version labels and release links during documentation
+  validation, including rendered header/footer links and anchors.
+- Preserve the 4.0.1 public execution contract; no runtime behavior changes.
+
 ## 4.0.1 — 2026-10-08
 
 - Settle the legacy command worker before propagating timeout/transport errors;

{sshscript-4.0.1 → sshscript-5.0.0}/MANIFEST.in

@@ -1,4 +1,7 @@
 include README.md LICENSE.txt RELEASING.md
+include AI_GUIDE.md
+include skills/sshscript/SKILL.md
+include skills/sshscript/references/agent-guide.md
 include CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md EXCEPTIONS.md SECURITY.md SUPPORT.md
 recursive-include tools *.py
 include tools/setup_openssh_ci.sh

{sshscript-4.0.1/src/sshscript.egg-info → sshscript-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sshscript
-Version: 4.0.1
+Version: 5.0.0
 Summary: Python automation for local processes, SSH, and SSHScript .spy files
 Author-email: "Yeh, Hsin-Yuan" <iapyeh@gmail.com>
 License-Expression: MIT
@@ -37,9 +37,12 @@ Dynamic: license-file
 [![CodeQL](https://github.com/iapyeh/sshscript/actions/workflows/codeql.yml/badge.svg?branch=release)](https://github.com/iapyeh/sshscript/actions/workflows/codeql.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/iapyeh/sshscript/blob/release/LICENSE.txt)
 
+**AI agent ready automation for local and remote commands.**
+
 SSHScript is a Python automation library for running commands locally and over
-SSH through one `Session` API. It also provides optional dollar syntax for
-compact `.spy` automation files.
+SSH through one `Session` API. It provides an agent guide, a portable skill
+bundle, and copyable prompts to help your AI agent use its execution contract.
+Optional dollar syntax supports compact `.spy` automation files.
 
 SSHScript aims to help engineers and AI agents execute, understand, and hand
 off automation reliably: identify the execution host, retain each command's
@@ -47,7 +50,7 @@ output and status, distinguish failure from timeout, and make cleanup and
 unknown termination explicit. A successful command exit is evidence about
 that command; verify the deployment or other application outcome separately.
 
-**Current release:** [4.0.1](https://github.com/iapyeh/sshscript/releases/tag/v4.0.1)
+**Current release:** [5.0.0](https://github.com/iapyeh/sshscript/releases/tag/v5.0.0)
 (Production/Stable) · **Python:** 3.11 or newer · **Tested:** Python
 3.11–3.14 on Linux and macOS
 
@@ -57,10 +60,45 @@ that command; verify the deployment or other application outcome separately.
 [Security](https://github.com/iapyeh/sshscript/security/policy) ·
 [Support](https://github.com/iapyeh/sshscript/blob/release/SUPPORT.md)
 
-**Version 4.0.1** introduces the incompatible 4.0 execution contract.
+**Version 5.0.0** preserves the 4.0 command execution contract and changes the
+default host-key source to the calling host. Provision its known_hosts file or
+select `known_hosts="local"` when migrating existing nested connections.
 Upgrade 3.1.5 automation using the migration guide and application regressions.
 See [version policy and migration](VERSIONING.md) before upgrading automation.
 
+## AI agent ready
+
+**Give your agent one URL:**
+[SSHScript for AI Agents](https://iapyeh.github.io/sshscript/v3a/ai-agents/).
+Prepare it for future automation or give it a task to complete now.
+
+- **A guide for agents:** version-aware API selection, exact input handling,
+  retained command results, timeouts, authentication and cleanup.
+- **A portable skill bundle:** `SKILL.md` with the agent guide and API and
+  version-policy references, ready to install through your agent's skill
+  mechanism.
+- **Prompts for humans:** copy a setup prompt to request skill installation and
+  a saved tool preference, or a task prompt to describe hosts, inputs and
+  expected results.
+
+Start with this prompt, even before you have a task:
+
+```text
+Read https://iapyeh.github.io/sshscript/v3a/ai-agents/ and the Agent Guide.
+If you support skills, download and install the complete skill bundle. If you
+support persistent preferences, save this preference: for future local or
+remote command execution and automation, first assess whether SSHScript is
+suitable and use it when appropriate. Report whether the skill can be loaded
+and the preference was saved, and explain any limits.
+For now, do not connect to remote hosts or run demonstration commands.
+```
+
+The guides are ordinary Markdown and web pages for agents that can read files
+or URLs. Skill installation and persistent preferences depend on the agent's
+capabilities. See the [repository AI entry](AI_GUIDE.md),
+[agent guide](skills/sshscript/references/agent-guide.md) and
+[skill instructions](skills/sshscript/SKILL.md) for the source documents.
+
 ## Recommended API
 
 Start with [the canonical API guide](API_GUIDE.md): version-labelled examples,
@@ -82,6 +120,7 @@ and [the cross-system test guide](src/sshscript/unittest/README.console-authenti
 
 ## Why SSHScript?
 
+- Prepare your AI agent with a dedicated guide, portable skill and setup prompts.
 - Use the same interface for local subprocesses and remote SSH commands.
 - Traverse nested SSH connections without rebuilding connection logic.
 - Keep ordinary Python functions, packages, exceptions, data processing, and
@@ -114,7 +153,7 @@ pin SSHScript and all transitive dependencies in your application's lock file.
 To install this release explicitly:
 
 ```sh
-python3 -m pip install "sshscript==3.1.5"
+python3 -m pip install "sshscript==5.0.0"
 ```
 
 Use `python3 -m pip install --upgrade sshscript` to upgrade. The optional
@@ -123,7 +162,8 @@ it never installs an update by itself.
 
 ## 60-second local quickstart
 
-This example uses the published 3.1.5 command API.
+This example runs on 5.0.0 and retains compatibility with the 3.1.5 command API.
+The metadata below records that older compatibility baseline.
 
 <!-- example: {"id":"readme-quickstart", "profile":"3.1.5", "stdout":"sshscript is ready\nexit code: 0\n"} -->
 ```python
@@ -374,10 +414,28 @@ Unknown and changed host keys are rejected unless the caller explicitly
 supplies a different Paramiko policy. Do not use automatic key acceptance in a
 production workflow unless a separate trusted bootstrap process has already
 verified the key. See the
-[SSHScript v3 documentation](https://iapyeh.github.io/sshscript/v3a/) for
+[SSHScript documentation](https://iapyeh.github.io/sshscript/v3a/) for
 nested connections, timeouts, file transfer, `sudo`, `su`, and interactive
 programs.
 
+## Host-key sources in 5.0
+
+SSHScript 5.0.0 uses `known_hosts="parent"` as the default: a local
+Session reads localhost's trust file; `host1.connect("host2")` reads host1's
+trust file over SFTP. This matches the host ownership of `pkey_path`.
+SSHScript 4.0.2 and earlier use localhost for all host-key checks.
+
+Set `session.set(known_hosts="chain")` to search from the calling Session
+through its ancestors to localhost. The nearest layer with a target record
+wins; a mismatch or read/parse error stops the connection. Set
+`session.set(known_hosts="local")` to preserve previous behavior.
+Each Session can set its own `known_hosts_path`; this path is not inherited.
+`connect(known_hosts=...)` overrides only one connection. `pkey_path` remains
+on the calling host for every strategy. `policy` handles only unknown keys;
+`AutoAddPolicy` does not write these trust files. See the
+[host-key source contract](API_GUIDE.md#host-key-sources-unreleased) for supported
+file formats, strict error handling and migration.
+
 ## Reusing SSH configuration
 
 Connections from a local session read `~/.ssh/config` if it exists. Supported

{sshscript-4.0.1 → sshscript-5.0.0}/README.md

@@ -6,9 +6,12 @@
 [![CodeQL](https://github.com/iapyeh/sshscript/actions/workflows/codeql.yml/badge.svg?branch=release)](https://github.com/iapyeh/sshscript/actions/workflows/codeql.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/iapyeh/sshscript/blob/release/LICENSE.txt)
 
+**AI agent ready automation for local and remote commands.**
+
 SSHScript is a Python automation library for running commands locally and over
-SSH through one `Session` API. It also provides optional dollar syntax for
-compact `.spy` automation files.
+SSH through one `Session` API. It provides an agent guide, a portable skill
+bundle, and copyable prompts to help your AI agent use its execution contract.
+Optional dollar syntax supports compact `.spy` automation files.
 
 SSHScript aims to help engineers and AI agents execute, understand, and hand
 off automation reliably: identify the execution host, retain each command's
@@ -16,7 +19,7 @@ output and status, distinguish failure from timeout, and make cleanup and
 unknown termination explicit. A successful command exit is evidence about
 that command; verify the deployment or other application outcome separately.
 
-**Current release:** [4.0.1](https://github.com/iapyeh/sshscript/releases/tag/v4.0.1)
+**Current release:** [5.0.0](https://github.com/iapyeh/sshscript/releases/tag/v5.0.0)
 (Production/Stable) · **Python:** 3.11 or newer · **Tested:** Python
 3.11–3.14 on Linux and macOS
 
@@ -26,10 +29,45 @@ that command; verify the deployment or other application outcome separately.
 [Security](https://github.com/iapyeh/sshscript/security/policy) ·
 [Support](https://github.com/iapyeh/sshscript/blob/release/SUPPORT.md)
 
-**Version 4.0.1** introduces the incompatible 4.0 execution contract.
+**Version 5.0.0** preserves the 4.0 command execution contract and changes the
+default host-key source to the calling host. Provision its known_hosts file or
+select `known_hosts="local"` when migrating existing nested connections.
 Upgrade 3.1.5 automation using the migration guide and application regressions.
 See [version policy and migration](VERSIONING.md) before upgrading automation.
 
+## AI agent ready
+
+**Give your agent one URL:**
+[SSHScript for AI Agents](https://iapyeh.github.io/sshscript/v3a/ai-agents/).
+Prepare it for future automation or give it a task to complete now.
+
+- **A guide for agents:** version-aware API selection, exact input handling,
+  retained command results, timeouts, authentication and cleanup.
+- **A portable skill bundle:** `SKILL.md` with the agent guide and API and
+  version-policy references, ready to install through your agent's skill
+  mechanism.
+- **Prompts for humans:** copy a setup prompt to request skill installation and
+  a saved tool preference, or a task prompt to describe hosts, inputs and
+  expected results.
+
+Start with this prompt, even before you have a task:
+
+```text
+Read https://iapyeh.github.io/sshscript/v3a/ai-agents/ and the Agent Guide.
+If you support skills, download and install the complete skill bundle. If you
+support persistent preferences, save this preference: for future local or
+remote command execution and automation, first assess whether SSHScript is
+suitable and use it when appropriate. Report whether the skill can be loaded
+and the preference was saved, and explain any limits.
+For now, do not connect to remote hosts or run demonstration commands.
+```
+
+The guides are ordinary Markdown and web pages for agents that can read files
+or URLs. Skill installation and persistent preferences depend on the agent's
+capabilities. See the [repository AI entry](AI_GUIDE.md),
+[agent guide](skills/sshscript/references/agent-guide.md) and
+[skill instructions](skills/sshscript/SKILL.md) for the source documents.
+
 ## Recommended API
 
 Start with [the canonical API guide](API_GUIDE.md): version-labelled examples,
@@ -51,6 +89,7 @@ and [the cross-system test guide](src/sshscript/unittest/README.console-authenti
 
 ## Why SSHScript?
 
+- Prepare your AI agent with a dedicated guide, portable skill and setup prompts.
 - Use the same interface for local subprocesses and remote SSH commands.
 - Traverse nested SSH connections without rebuilding connection logic.
 - Keep ordinary Python functions, packages, exceptions, data processing, and
@@ -83,7 +122,7 @@ pin SSHScript and all transitive dependencies in your application's lock file.
 To install this release explicitly:
 
 ```sh
-python3 -m pip install "sshscript==3.1.5"
+python3 -m pip install "sshscript==5.0.0"
 ```
 
 Use `python3 -m pip install --upgrade sshscript` to upgrade. The optional
@@ -92,7 +131,8 @@ it never installs an update by itself.
 
 ## 60-second local quickstart
 
-This example uses the published 3.1.5 command API.
+This example runs on 5.0.0 and retains compatibility with the 3.1.5 command API.
+The metadata below records that older compatibility baseline.
 
 <!-- example: {"id":"readme-quickstart", "profile":"3.1.5", "stdout":"sshscript is ready\nexit code: 0\n"} -->
 ```python
@@ -343,10 +383,28 @@ Unknown and changed host keys are rejected unless the caller explicitly
 supplies a different Paramiko policy. Do not use automatic key acceptance in a
 production workflow unless a separate trusted bootstrap process has already
 verified the key. See the
-[SSHScript v3 documentation](https://iapyeh.github.io/sshscript/v3a/) for
+[SSHScript documentation](https://iapyeh.github.io/sshscript/v3a/) for
 nested connections, timeouts, file transfer, `sudo`, `su`, and interactive
 programs.
 
+## Host-key sources in 5.0
+
+SSHScript 5.0.0 uses `known_hosts="parent"` as the default: a local
+Session reads localhost's trust file; `host1.connect("host2")` reads host1's
+trust file over SFTP. This matches the host ownership of `pkey_path`.
+SSHScript 4.0.2 and earlier use localhost for all host-key checks.
+
+Set `session.set(known_hosts="chain")` to search from the calling Session
+through its ancestors to localhost. The nearest layer with a target record
+wins; a mismatch or read/parse error stops the connection. Set
+`session.set(known_hosts="local")` to preserve previous behavior.
+Each Session can set its own `known_hosts_path`; this path is not inherited.
+`connect(known_hosts=...)` overrides only one connection. `pkey_path` remains
+on the calling host for every strategy. `policy` handles only unknown keys;
+`AutoAddPolicy` does not write these trust files. See the
+[host-key source contract](API_GUIDE.md#host-key-sources-unreleased) for supported
+file formats, strict error handling and migration.
+
 ## Reusing SSH configuration
 
 Connections from a local session read `~/.ssh/config` if it exists. Supported

{sshscript-4.0.1 → sshscript-5.0.0}/SECURITY.md

@@ -65,11 +65,20 @@ termination. Verify application outcomes and reconcile unknown termination.
 
 ### SSH identity and host keys
 
-SSH connections load system host keys and reject unknown or changed keys by
-default. The application is responsible for provisioning `known_hosts` and
+SSH connections reject unknown or changed keys by default. SSHScript 4.0.2 and earlier
+load localhost system host keys. SSHScript 5.0.0 defaults to
+`known_hosts="parent"`, reading the calling Session host's trust file. Remote
+trust files are read over SFTP using the original SSH login account; verification
+still runs locally. `"chain"` trusts the nearest source with a target record;
+it never falls back after a mismatch or file error. Trusting a parent's records
+also trusts that host/account to maintain them. Use `"local"` to retain the
+previous source selection. See the [host-key source contract](API_GUIDE.md#host-key-sources-unreleased).
+
+The application is responsible for provisioning `known_hosts` and
 verifying a new fingerprint through an independent channel. Supplying an
 automatic-acceptance Paramiko policy is an explicit opt-out from this default
 and is not recommended for production enrollment.
+AutoAddPolicy does not persist keys into these local or remote trust files.
 
 SSH authentication ultimately follows Paramiko and server policy. Prefer an
 SSH agent, managed key, or secret manager. Never store passwords or private