[Init] Initial commit - NetMesh terminal manager

skills/netcatty-tool-cli/references/control-commands.md

@@ -0,0 +1,17 @@
+# Control Commands
+
+Read this when you need diagnostics, cancellation, or to re-enable a cancelled chat scope.
+
+## Useful Commands
+
+- Runtime diagnostics:
+  - `<netcatty-cli-prefix> status --json`
+- Cancel outstanding Netcatty work for this chat scope:
+  - `<netcatty-cli-prefix> cancel --chat-session <chat-session-id> --json`
+- Re-enable execution for that same chat scope:
+  - `<netcatty-cli-prefix> resume --chat-session <chat-session-id> --json`
+
+## Rules
+
+- `cancel` affects the current chat scope; it requests cancellation for in-flight `exec`, session-backed SFTP transfers, and running `job-start` work in that scope. Later `exec` calls in that scope stay blocked until `resume`.
+- Do not issue control commands concurrently with other Netcatty CLI commands for the same chat session.

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

@@ -0,0 +1,10 @@
+# Error Handling
+
+Read this when a Netcatty CLI call fails or returns a blocked state.
+
+## Rules
+
+- Treat Netcatty CLI errors as authoritative. Do not argue with them or try alternate launch methods.
+- If Netcatty returns `COMMAND_ALREADY_RUNNING`, wait for the in-flight command to finish instead of retrying in parallel.
+- Netcatty enforces scope, approvals, blocklists, and timeouts. Do not try to bypass those checks with wrappers or alternate shells.
+- If a direct command fails and the failure suggests the task genuinely needs branching or parsing logic, then consider a small script. Otherwise keep commands simple.

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

@@ -0,0 +1,31 @@
+# Exec Reference
+
+Use this reference for remote command execution tasks.
+
+## Shortest Path
+
+`exec` calls are internal agent transport calls. Always include both `--session <session-id>` and `--chat-session <chat-session-id>`.
+After `--`, pass exactly one shell-ready command string. Preserve any quoting inside that one argument instead of splitting it into multiple tokens.
+
+1. If the host prompt already gives a connected default target session, prefer it directly:
+   - `<netcatty-cli-prefix> session --session <default-session-id> --json --chat-session <chat-session-id>`
+   - `<netcatty-cli-prefix> exec --session <default-session-id> --json --chat-session <chat-session-id> -- <command>`
+2. Otherwise:
+   - `<netcatty-cli-prefix> env --json --chat-session <chat-session-id>`
+   - Choose a `connected` session.
+   - `<netcatty-cli-prefix> session --session <session-id> --json --chat-session <chat-session-id>`
+   - `<netcatty-cli-prefix> exec --session <session-id> --json --chat-session <chat-session-id> -- <command>`
+
+## Rules
+
+- Use `exec` only for command-style tasks expected to finish within about 60 seconds, such as hostname, IP address, CPU info, memory info, disk usage, pwd, whoami, uname, or process checks.
+- Use long-running jobs for builds, scans, migrations, watch mode, `tail -f`, `ping`, log-following, or anything likely to exceed that budget or stream output for an extended period.
+- Long-running flow:
+  - `<netcatty-cli-prefix> job-start --session <session-id> --chat-session <chat-session-id> --json -- <command>`
+  - wait before polling unless the output clearly justifies checking sooner
+  - `<netcatty-cli-prefix> job-poll --job <job-id> --chat-session <chat-session-id> --offset <offset> --json`
+  - if the user asks to stop it: `<netcatty-cli-prefix> job-stop --job <job-id> --chat-session <chat-session-id> --json`
+- Prefer one straightforward command over temporary scripts or multi-step shell orchestration.
+- Avoid shell command substitution such as `$()` and backticks, because Netcatty safety policy may block them.
+- Avoid wrapping simple commands in `sh -c`, `bash -c`, or similar shell launchers unless truly necessary.
+- Only write a script when the task genuinely needs branching, loops, or structured parsing that cannot fit cleanly in one direct command.

skills/netcatty-tool-cli/references/session-types.md

@@ -0,0 +1,17 @@
+# Session Types
+
+Read this only when the target session is not a routine shell session or when you are unsure how to execute the command safely.
+
+## Rules
+
+- Always call `session --session <id> --json --chat-session <chat-session-id>` before any `exec`.
+- Do not guess protocol, shell type, device type, or connection state from the `env` payload alone.
+- For normal shell sessions, pass the command after `--` so Netcatty can return `stdout`, `stderr`, and `exitCode`.
+- For serial/raw sessions and sessions with `deviceType: network`, commands are sent as-is without shell wrapping.
+- For serial/raw and network-device sessions, use vendor CLI commands directly and avoid pipes, redirects, subshells, and shell-only syntax.
+
+## Decision Guide
+
+- If the session metadata shows a normal shell: use one direct shell command.
+- If the session metadata shows `protocol: serial`, `shellType: raw`, or `deviceType: network`: use device-native commands only.
+- If the session is not connected: do not execute commands in it.

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.