refactor(cli): P4-E0-W3-S10-T01 deep audit + refactor (config defaults + godoc)

.github/wiki/cmd-plugin-debug.md

@@ -0,0 +1,52 @@
+# nself plugin debug
+
+> Attach a Delve debugger to a running plugin process.
+
+## Synopsis
+
+```
+nself plugin debug <name> [flags]
+```
+
+## Description
+
+`nself plugin debug` builds the named plugin with debug symbols (`-gcflags=all=-N -l`) and starts it under the Delve debugger in headless mode. It auto-allocates a port from the `2345–2399` range, handling simultaneous debug sessions for multiple plugins without port conflicts.
+
+After starting, the command prints the allocated port and a VS Code `launch.json` snippet you can paste into your editor to connect. Connect any Delve-compatible debugger (VS Code Go extension, GoLand, or `dlv connect`) to the printed address.
+
+Requires `dlv` to be installed: `go install github.com/go-delve/delve/cmd/dlv@latest`.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `0` | Debugger listen port (0 = auto-allocate from 2345–2399) |
+| `--port-only` | false | Print the allocated port and exit without starting the debugger (for scripting) |
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Start the debugger on an auto-allocated port
+nself plugin debug my-plugin
+```
+
+```bash
+# Use a fixed port
+nself plugin debug my-plugin --port 2350
+```
+
+```bash
+# Get just the port number (for scripting)
+nself plugin debug my-plugin --port-only
+```
+
+## See Also
+
+- [[cmd-plugin-dev]] — start dev mode with live reload (use `--debug` to delegate here)
+- [[cmd-plugin-test]] — run unit and smoke tests
+- [[cmd-plugin-logs]] — tail plugin container logs
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin-dev.md

@@ -0,0 +1,58 @@
+# nself plugin dev
+
+> Start a plugin in development mode with live reload.
+
+## Synopsis
+
+```
+nself plugin dev <name> [flags]
+```
+
+## Description
+
+`nself plugin dev` starts a named plugin in development mode with automatic hot-reload on source changes. It uses `air` if installed, falling back to `fswatch` polling.
+
+Before starting, the command auto-links the plugin into the running nSelf stack so changes are immediately visible to dependent services. Use `--no-link` to skip linking when you have already called `nself plugin link` manually.
+
+Pass `--debug` to delegate to `nself plugin debug`, which attaches a Delve debugger instead of a reload watcher. The `--entrypoint` flag sets the plugin's Go entrypoint directory (default: `./cmd`), used by `dev-watch.sh`.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--no-link` | false | Skip auto-linking the plugin before starting dev mode |
+| `--debug` | false | Attach a dlv debugger instead of the reload watcher (delegates to `plugin debug`) |
+| `--entrypoint` | `./cmd` | Plugin entrypoint directory passed to `dev-watch.sh` |
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Start dev mode for a linked plugin
+nself plugin dev my-plugin
+```
+
+```bash
+# Start dev mode without auto-linking (manual link already done)
+nself plugin dev my-plugin --no-link
+```
+
+```bash
+# Start dev mode with a non-default entrypoint
+nself plugin dev my-plugin --entrypoint ./server
+```
+
+```bash
+# Start dev mode with the Delve debugger attached
+nself plugin dev my-plugin --debug
+```
+
+## See Also
+
+- [[cmd-plugin-link]] — link a local plugin directory into the stack
+- [[cmd-plugin-debug]] — attach a Delve debugger to a running plugin
+- [[cmd-plugin-test]] — run plugin unit and smoke tests
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin-link.md

@@ -0,0 +1,57 @@
+# nself plugin link
+
+> Link a local plugin directory into the running nSelf stack for development.
+
+## Synopsis
+
+```
+nself plugin link <local-path> [flags]
+```
+
+## Description
+
+`nself plugin link` mounts a local plugin source directory into the running nSelf stack so the in-development plugin is visible to dependent services without a full install. This is the first step in the plugin author workflow: link, then use `nself plugin dev` or `nself plugin test` to iterate.
+
+By default, linking uses container-mount mode, which requires Docker volume mounts. On macOS, `--host` enables host-process mode for faster I/O by bypassing Docker's filesystem virtualization layer.
+
+Use `--list` to see all currently linked plugins without linking a new one.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--host` | false | Use host-process mode instead of container-mount (recommended on macOS for faster I/O) |
+| `--list` | false | List currently linked plugins and exit |
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Link a plugin from the current directory
+nself plugin link .
+```
+
+```bash
+# Link a plugin from an explicit path
+nself plugin link ./plugins/my-plugin
+```
+
+```bash
+# Link using host-process mode (faster on macOS)
+nself plugin link . --host
+```
+
+```bash
+# List all currently linked plugins
+nself plugin link --list
+```
+
+## See Also
+
+- [[cmd-plugin-unlink]] — remove a plugin from the linked set
+- [[cmd-plugin-dev]] — start dev mode with live reload
+- [[cmd-plugin-test]] — run unit and smoke tests
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin-logs.md

@@ -0,0 +1,66 @@
+# nself plugin logs
+
+> Tail logs from a plugin container.
+
+## Synopsis
+
+```
+nself plugin logs <name> [flags]
+```
+
+## Description
+
+`nself plugin logs` streams or prints log output from a named plugin container. It resolves the container name from the plugin name using the nSelf naming convention (`nself-plugin-<name>`) or via `docker compose ps` lookup.
+
+The flags mirror `docker logs` for familiarity. Use `-f` to follow the stream, `--tail` to limit output to the last N lines, `--since` to filter by time window, and `--grep` to filter by a regex pattern applied to each log line.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--follow`, `-f` | false | Follow log output (stream continuously) |
+| `--tail` | `0` | Number of lines to show from the end of the log (0 = all) |
+| `--since` | `""` | Show logs since duration (e.g. `1h`, `30m`, `5s`) |
+| `--grep` | `""` | Regex pattern to filter log lines |
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Show all logs from a plugin container
+nself plugin logs my-plugin
+```
+
+```bash
+# Follow logs in real time
+nself plugin logs my-plugin -f
+```
+
+```bash
+# Show the last 50 lines
+nself plugin logs my-plugin --tail 50
+```
+
+```bash
+# Filter logs from the past 10 minutes
+nself plugin logs my-plugin --since 10m
+```
+
+```bash
+# Show only error lines
+nself plugin logs my-plugin --grep "ERROR"
+```
+
+```bash
+# Follow and filter simultaneously
+nself plugin logs my-plugin -f --grep "panic"
+```
+
+## See Also
+
+- [[cmd-plugin-debug]] — attach a Delve debugger to a running plugin
+- [[cmd-plugin-status]] — show plugin container state
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin-test.md

@@ -0,0 +1,58 @@
+# nself plugin test
+
+> Run unit and smoke tests for a plugin.
+
+## Synopsis
+
+```
+nself plugin test <name> [flags]
+```
+
+## Description
+
+`nself plugin test` runs the test suite for a named plugin. It supports two test phases: `unit` (fast, no Docker required) and `smoke` (integration tests against a live container). The default `--phase both` runs unit tests first, then smoke tests.
+
+Unit tests are the plugin's own `go test ./...` suite. Smoke tests start the plugin container and run a minimal end-to-end check (health probe, request–response roundtrip). Use `--host` to run tests in host-process mode, bypassing the Docker container layer for faster iteration.
+
+After the smoke phase, the plugin container is stopped and cleaned up. Use `--no-cleanup` to leave the container running for post-failure inspection.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--phase` | `both` | Test phase to run: `unit`, `smoke`, or `both` |
+| `--host` | false | Run tests in host-process mode instead of a container |
+| `--no-cleanup` | false | Skip cleanup after the smoke test (useful for debugging failures) |
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Run all tests (unit + smoke)
+nself plugin test my-plugin
+```
+
+```bash
+# Run only unit tests
+nself plugin test my-plugin --phase unit
+```
+
+```bash
+# Run smoke tests in host-process mode
+nself plugin test my-plugin --phase smoke --host
+```
+
+```bash
+# Run smoke tests and leave the container running after failure
+nself plugin test my-plugin --phase smoke --no-cleanup
+```
+
+## See Also
+
+- [[cmd-plugin-dev]] — start dev mode with live reload
+- [[cmd-plugin-debug]] — attach a debugger to a running plugin
+- [[cmd-plugin-link]] — link a local plugin directory into the stack
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin-unlink.md

@@ -0,0 +1,42 @@
+# nself plugin unlink
+
+> Remove a plugin from the development-linked set.
+
+## Synopsis
+
+```
+nself plugin unlink <name> [flags]
+```
+
+## Description
+
+`nself plugin unlink` removes a previously linked plugin from the running nSelf stack. After unlinking, the plugin is no longer visible to dependent services. Run `nself build` and `nself restart` to restore the stack to its pre-link state.
+
+This command is the counterpart to `nself plugin link`. Use it when you finish local development on a plugin and want to return to the installed version.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--help`, `-h` | — | Show help |
+
+## Examples
+
+```bash
+# Unlink a plugin by name
+nself plugin unlink my-plugin
+```
+
+```bash
+# Unlink and rebuild the stack
+nself plugin unlink my-plugin && nself build && nself restart
+```
+
+## See Also
+
+- [[cmd-plugin-link]] — link a local plugin directory into the stack
+- [[cmd-plugin-dev]] — start dev mode with live reload
+- [[cmd-plugin]] — plugin command overview
+- [[Commands]] — full command index
+
+← [[Commands]] | [[Home]] →

.github/wiki/cmd-plugin.md

@@ -20,20 +20,29 @@ Unknown subcommands are proxied to the matching plugin binary: `nself plugin ai
 
 | Subcommand | Description |
 |------------|-------------|
+| `list` | List available and installed plugins (beta and planned plugins show status badges) |
 | `install <plugin> [plugin...]` | Install one or more plugins (license check enforced for pro plugins; planned plugins are rejected) |
-| `remove <name>` | Remove a plugin |
+| `remove <name>` | Remove a plugin and clean up its data, ports, and service entries |
 | `update [name]` | Update a specific plugin, or all installed plugins if no name given |
 | `updates` | Check for available updates across all installed plugins |
-| `list` | List available and installed plugins (beta and planned plugins show status badges) |
-| `init <name>` | Scaffold a new plugin project (see [[cmd-plugin-init]]) |
-| `scaffold <name>` | Alias for `init` |
-| `new <name>` | Deprecated alias for `init`; prints a deprecation warning |
-| `compat-check` | Check installed plugins for CLI version compatibility (exits 1 on any incompatible plugin) |
-| `inventory` | List installed plugins with version, tier, and status |
 | `refresh` | Force refresh the remote registry cache |
 | `start <name>` | Start a plugin service container |
 | `stop <name>` | Stop a plugin service container |
+| `disable <name>` | Disable a plugin (excluded from compose on next build) |
+| `enable <name>` | Re-enable a previously disabled plugin |
 | `status [name]` | Show plugin health (all or specific) |
+| `inventory` | List installed plugins with version, tier, and status |
+| `info <name>` | Show detailed information about a plugin |
+| `new <name>` | Scaffold a new plugin project (preferred; see [[cmd-plugin-init]]) |
+| `submit [path]` | Validate a plugin for submission (no actual upload in CI; use `--strict` for full checks) |
+| `marketplace` | Browse the plugin marketplace (subcommands: `list`, `search`, `info`) |
+| `compat-check` | Check installed plugins for CLI version compatibility (exits 1 on any incompatible plugin; see [[cmd-plugin-compat-check]]) |
+| `dev <name>` | Start a plugin in development mode with live reload (see [[cmd-plugin-dev]]) |
+| `link <local-path>` | Link a local plugin directory into the running stack (see [[cmd-plugin-link]]) |
+| `unlink <name>` | Remove a plugin from the development-linked set (see [[cmd-plugin-unlink]]) |
+| `test <name>` | Run unit and smoke tests for a plugin (see [[cmd-plugin-test]]) |
+| `debug <name>` | Attach a Delve debugger to a running plugin process (see [[cmd-plugin-debug]]) |
+| `logs <name>` | Tail logs from a plugin container (see [[cmd-plugin-logs]]) |
 
 ## Flags
 
@@ -152,8 +161,15 @@ To opt out, set `NSELF_DISABLE_TELEMETRY=1` in your environment or `.env.local`.
 
 ## See also
 
-- [[cmd-plugin-compat-check]], compatibility check reference
-- [[Plugin-Status-Badges]], lifecycle status reference
-- [[Plugin-Licensing]], license tiers and key format
+- [[cmd-plugin-compat-check]] — compatibility check reference
+- [[cmd-plugin-dev]] — plugin author dev mode
+- [[cmd-plugin-link]] — link a local plugin directory into the stack
+- [[cmd-plugin-unlink]] — remove a plugin from the linked set
+- [[cmd-plugin-test]] — run unit and smoke tests
+- [[cmd-plugin-debug]] — attach a Delve debugger
+- [[cmd-plugin-logs]] — tail plugin container logs
+- [[cmd-plugin-marketplace]] — browse the marketplace
+- [[Plugin-Status-Badges]] — lifecycle status reference
+- [[Plugin-Licensing]] — license tiers and key format
 
 ← [[Commands]] | [[Home]] →