Initial commit: NetMesh smart ops platform with 3D topology, inspection reports, RCA and AI ops assistant

skills/netcatty-tool-cli/references/sftp.md

@@ -0,0 +1,42 @@
+# SFTP Reference
+
+Use this reference for remote file or directory tasks.
+
+## Default Path
+
+- Treat file and directory tasks as SFTP tasks by default, not shell tasks.
+- If the user explicitly says to use only `sftp`, do not call `exec`.
+- Every `sftp` command must include both `--session <session-id>` and `--chat-session <chat-session-id>`.
+- Do not use reusable SFTP handles or `--sftp <id>`.
+- After choosing a target session, first run `session --session <id> --json --chat-session <chat-session-id>` and inspect the returned metadata.
+- Use SFTP only when that `session` result shows a connected SSH-backed session. For local, Mosh, Telnet, serial/raw, or network-device sessions, do not use SFTP.
+- Keep path semantics strict:
+  - `--remote-path` always means a path on the remote host.
+  - `--local-path` always means a path on the local machine running Netcatty.
+- If the user says "download" to a local destination such as `/tmp`, `~/Downloads`, or Desktop, use `sftp download`.
+- If the user says to create or modify a file on the remote host, use `sftp write`, `sftp upload`, or another remote SFTP operation. Do not reinterpret that as a local download.
+
+## One-Off Commands
+
+- List a directory:
+  - `<netcatty-cli-prefix> sftp list --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Read a file:
+  - `<netcatty-cli-prefix> sftp read --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Write a small text file with known content:
+  - `<netcatty-cli-prefix> sftp write --session <session-id> --remote-path <remote-path> --content <text> --json --chat-session <chat-session-id>`
+- Download a remote file to an existing local path:
+  - `<netcatty-cli-prefix> sftp download --session <session-id> --remote-path <remote-path> --local-path <local-path> --json --chat-session <chat-session-id>`
+- Upload an existing local file:
+  - `<netcatty-cli-prefix> sftp upload --session <session-id> --local-path <local-path> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+- Delete a remote path:
+  - `<netcatty-cli-prefix> sftp delete --session <session-id> --remote-path <remote-path> --json --chat-session <chat-session-id>`
+
+## Rules
+
+- Use `sftp write` directly for creating or updating a small text file with known content.
+- Use `sftp upload` only when a real local file already exists and must be transferred.
+- Use `sftp download` when the result must be saved to the local filesystem.
+- Do not create temporary local files just to upload text that could be sent with `sftp write`.
+- Do not use `sftp read` as a substitute for `sftp download` when the user asked for a local saved file.
+- Do not use `sftp write` as a substitute for `sftp download`; writing to `/tmp/foo` with `sftp write` writes to the remote host's `/tmp`, not the local machine.
+- Do not use shell commands like `cat`, `touch`, redirection, or ad hoc SCP/SSH usage for remote file tasks.