updating and refining plugin system refactor

docs/scp_plugin_tutorial.md

@@ -11,16 +11,16 @@ The implementation lives in [plugins/scp/__init__.py](plugins/scp/__init__.py).
 
 The SCP plugin mirrors the FTP walkthrough, but on top of SSH:
 
-- `search-file -plugin scp ...` lists remote files and folders over SFTP.
+- `search-file -plugin scp -instance <name> ...` lists remote files and folders over SFTP.
 - plain `@N` on a folder drills into that directory.
-- plain `@N` on a file runs `download-file -plugin scp -url ...`.
+- plain `@N` on a file runs `download-file -plugin scp -instance <name> -url ...`.
 - `@N | add-file -store ...` downloads first, then ingests the local temp file.
-- `add-file -plugin scp -path ...` uploads a local file to the configured remote path.
+- `add-file -plugin scp -instance <name> -path ...` uploads a local file to the configured remote path.
 
 ## Example Config
 
 ```toml
-[provider.scp]
+[provider.scp.work]
 host = "ssh.example.com"
 port = 22
 username = "deploy"
@@ -31,11 +31,20 @@ timeout = 20
 search_depth = 1
 allow_agent = true
 look_for_keys = true
+
+[provider.scp.archive]
+host = "ssh-archive.example.com"
+port = 2222
+username = "archive"
+key_path = "C:/Users/Admin/.ssh/archive_ed25519"
+base_path = "/srv/archive"
+timeout = 20
 ```
 
 Notes:
 
-- `host` and `username` are required for the plugin to validate.
+- `work` and `archive` are instance names; use them with `-instance work` or `-instance archive`.
+- `host` and `username` are required for each instance to validate.
 - You can use password auth, key auth, or both.
 - `base_path` is both the default search root and the default upload directory.
 
@@ -44,25 +53,25 @@ Notes:
 List the configured base path:
 
 ```powershell
-search-file -plugin scp "*"
+search-file -plugin scp -instance work "*"
 ```
 
 Search by filename:
 
 ```powershell
-search-file -plugin scp "invoice"
+search-file -plugin scp -instance work "invoice"
 ```
 
 Search another subtree with deeper recursion:
 
 ```powershell
-search-file -plugin scp "path:/srv/files/releases depth:2 *.zip"
+search-file -plugin scp -instance work "path:/srv/files/releases depth:2 *.zip"
 ```
 
 Show only folders:
 
 ```powershell
-search-file -plugin scp "path:/srv/files type:folder *"
+search-file -plugin scp -instance work "path:/srv/files type:folder *"
 ```
 
 ## Selection Flow
@@ -70,21 +79,21 @@ search-file -plugin scp "path:/srv/files type:folder *"
 Folder rows are navigation rows:
 
 ```powershell
-search-file -plugin scp "*"
+search-file -plugin scp -instance work "*"
 @2
 ```
 
 File rows carry an explicit row action, so terminal selection downloads directly:
 
 ```powershell
-search-file -plugin scp "report"
+search-file -plugin scp -instance work "report"
 @1
 ```
 
 That expands to the equivalent of:
 
 ```powershell
-download-file -plugin scp -url scp://ssh.example.com/srv/files/report.pdf
+download-file -plugin scp -instance work -url scp://ssh.example.com/srv/files/report.pdf
 ```
 
 ## Download And Add-File Flow
@@ -92,14 +101,14 @@ download-file -plugin scp -url scp://ssh.example.com/srv/files/report.pdf
 Download into a local folder:
 
 ```powershell
-search-file -plugin scp "report"
+search-file -plugin scp -instance work "report"
 @1 | download-file -path C:\Downloads
 ```
 
 Ingest a selected remote file into a configured store backend:
 
 ```powershell
-search-file -plugin scp "report"
+search-file -plugin scp -instance work "report"
 @1 | add-file -store tutorial
 ```
 
@@ -108,13 +117,14 @@ Why this works:
 - file rows advertise `_selection_action` for `download-file`
 - `add-file` selection replay inserts that provider download stage before ingest
 - the plugin also implements `resolve_pipe_result_download()` for provider-owned SCP rows
+- file rows also carry the chosen `instance`, so replay stays bound to the same SSH target
 
 ## Upload Flow
 
 Upload a local file to the configured remote `base_path`:
 
 ```powershell
-add-file -plugin scp -path C:\Media\report.pdf
+add-file -plugin scp -instance archive -path C:\Media\report.pdf
 ```
 
 ## Implementation Notes
@@ -127,10 +137,10 @@ The plugin uses SFTP for directory listing because SCP itself is a transfer prot
 ## Recommended Demo Commands
 
 ```powershell
-search-file -plugin scp "*"
-search-file -plugin scp "path:/srv/files depth:2 *.zip"
+search-file -plugin scp -instance work "*"
+search-file -plugin scp -instance work "path:/srv/files depth:2 *.zip"
 @1
 @1 | download-file -path C:\Downloads
 @1 | add-file -store tutorial
-add-file -plugin scp -path C:\Media\report.pdf
+add-file -plugin scp -instance archive -path C:\Media\report.pdf
 ```