From da0170d2c0ff56e9f85abd8ca62e0b6a10a25e9a Mon Sep 17 00:00:00 2001
From: m1ngsama <contact@m1ng.space>
Date: Sun, 24 May 2026 12:43:28 +0800
Subject: [PATCH] docs: refresh command contribution guidance

---
 docs/CHANGELOG.md         |  3 +++
 docs/CONTRIBUTING.md      | 36 ++++++++++++++++++++++++++----------
 docs/Development-Guide.md | 26 ++++++++++++++------------
 3 files changed, 43 insertions(+), 22 deletions(-)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 8d3901c..90df3da 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -14,6 +14,9 @@
   instead of localizing the `[options]` metavariable.
 - Moved SSH exec help rows into an `exec_catalog` module so command metadata
   no longer lives as one large translated blob inside the shared i18n table.
+- Refreshed contributor and development guidance so new commands are added
+  through `command_catalog`, `exec_catalog`, and `i18n_text` instead of stale
+  `ssh_server.c` / inline-`strcmp` instructions.
 - Renamed the internal language state from help-oriented names to
   UI-language names (`ui_lang_t`, `client->ui_lang`, and
   `i18n_*_ui_lang`) so future i18n work has a correctly named seam.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index e2097b1..cb31305 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -3,17 +3,19 @@
 ## Build
 
 ```sh
-make              # normal build
-make debug        # with symbols
-make asan         # AddressSanitizer
-make release      # optimized
+make                    # normal build
+make debug              # with symbols
+make asan               # AddressSanitizer
+make release            # optimized
+make release-check      # release preflight
 ```
 
 ## Test
 
 ```sh
-./test_basic.sh           # functional tests
-./test_stress.sh 20 60    # 20 clients, 60 seconds
+make test                 # unit + integration tests
+make ci-test              # local CI-equivalent checks
+make stress-test          # concurrent-client stress test
 ```
 
 ## Debug
@@ -34,10 +36,21 @@ make check
 
 ```
 main.c           → entry point, signal handling
-ssh_server.c     → SSH protocol, client threads
+cli_text.c       → startup CLI text
+command_catalog.c → COMMAND-mode command metadata
+commands.c       → COMMAND-mode command dispatch
+exec_catalog.c   → SSH exec help metadata
+exec.c           → SSH exec command dispatch
+ssh_server.c     → SSH listener setup
+bootstrap.c      → SSH authentication/session bootstrap
+input.c          → interactive session loop
 chat_room.c      → client list, message broadcast
+history_view.c   → message viewport and scroll state
+i18n.c           → UI language and locale selection
+i18n_text.c      → shared UI text catalog
 message.c        → persistent storage
 tui.c            → terminal rendering
+tui_status.c     → status/input-line rendering
 utf8.c           → UTF-8 string handling
 ```
 
@@ -70,9 +83,12 @@ utf8.c           → UTF-8 string handling
 
 ## Adding Features
 
-1. Add new command in `execute_command()` (ssh_server.c:190)
-2. Add new mode in `client_mode_t` enum (common.h:30)
-3. Add new vim key in `handle_key()` (ssh_server.c:220)
+1. Add interactive command metadata in `src/command_catalog.c`.
+2. Add interactive command behavior in `src/commands.c`.
+3. Add SSH exec metadata in `src/exec_catalog.c` and dispatch in `src/exec.c`
+   only when the feature should be scriptable.
+4. Put shared localized strings in `src/i18n_text.c`.
+5. Add or update the narrowest unit/integration test for the behavior.
 
 ## Debugging Tips
 
diff --git a/docs/Development-Guide.md b/docs/Development-Guide.md
index 95afdd2..15c1f10 100644
--- a/docs/Development-Guide.md
+++ b/docs/Development-Guide.md
@@ -357,29 +357,31 @@ void utf8_remove_last_word(char *str) {
 
 ### Adding a New Command
 
-1. **For interactive COMMAND mode, add to `commands_dispatch()` in `src/commands.c`:**
+1. **For interactive COMMAND mode, add command metadata in `src/command_catalog.c`:**
 ```c
-if (strcmp(cmd, "newcmd") == 0) {
-    pos += snprintf(output + pos, sizeof(output) - pos,
-                   "New command output\n");
+{
+    {TNT_COMMAND_NEWCMD, "newcmd", {"newcmd", NULL}, false},
+    ":newcmd", ":newcmd",
+    "Show new output", "显示新输出",
+    ":newcmd", ":newcmd", 3
 }
 ```
 
-2. **For SSH exec mode, add the stable command path in `src/exec.c` if it should work non-interactively.**
+2. **Add interactive behavior in `src/commands.c` by switching on the command ID.**
 
-3. **Move user-facing strings through `src/i18n.c` when they need localization or are reused.**
+3. **For SSH exec mode, add help metadata in `src/exec_catalog.c` and the stable command path in `src/exec.c` if it should work non-interactively.**
 
-4. **Update user help text in `src/manual_text.c` and `src/help_text.c`:**
-```c
-"AVAILABLE COMMANDS:\n"
-"  newcmd         - Description of new command\n"
-```
+4. **Move shared user-facing strings through `src/i18n_text.c` when they need localization or are reused.  Keep command syntax and metavariables ASCII.**
 
-5. **Add tests in the narrowest target:**
+5. **Update user help surfaces through their catalogs.  Avoid duplicating command rows by hand.**
+
+6. **Add tests in the narrowest target:**
 ```sh
 tests/test_exec_mode.sh          # exec command behavior
 tests/test_interactive_input.sh  # COMMAND-mode/TUI behavior
 tests/unit/test_i18n.c           # localized shared text
+tests/unit/test_command_catalog.c # interactive command metadata
+tests/unit/test_exec_catalog.c   # exec command help metadata
 ```
 
 ### Adding a New Keybinding