@succsoft/succapp 5.0.7 → 5.0.8

package/dist/cli/l10n/bundle.l10n.json

@@ -99,6 +99,7 @@
 	"err.net.invalidResponse": "Invalid remote response format",
 	"err.net.invalidResponse.desc": "The remote response does not match the current protocol requirements. Check the service version or contact the administrator.",
 	"err.net.invalidResponse.dbTableDescribeEmpty.hint": "Check whether data source {dataSource} and table {tableName} exist.",
+	"err.db.connectorNotFound": "Database connector is not available: {name}.",
 	"err.db.tableNotFound": "Database table does not exist: {tableName}",
 	"err.cli.unknownCommand": "Unknown command: {commandName}",
 	"err.cli.unknownCommand.hint": "Run '{helpCommand}' to view available commands.",
@@ -245,27 +246,29 @@
 	"workspace.sync.progress.upgradeMeta.checked": "Checked {0} metadata file(s): {1} upgradeable.",
 	"workspace.sync.progress.upgradeMeta.done": "Upgraded metadata files: {0} changed, {1} failed, {2} checked.",
 	"workspace.sync.progress.upgradeMeta.scan": "Scanning metadata files",
+	"workspace.sync.push.upgradeRequired": "Metadata file {0} must be upgraded before pushing. Run succapp workspace file upgrade or use Upgrade File in VS Code.",
 	"cli.cmd.common.desc": "Common commands.",
 	"cli.cmd.common.summary": "common commands",
 	"cli.cmd.common.title": "Common",
 	"cli.cmd.root.summary": "SuccApp command line interface.",
 	"cli.host.localeFallback": "Locale {0} is not available; using default messages.",
 	"cli.opt.help": "Show this help.",
-	"cli.opt.json": "Write NDJSON for scripts; binary content results use Base64.",
+	"cli.opt.json": "Write NDJSON for scripts; file content, including text, uses Base64. Diagnostics go to stderr.",
 	"cli.opt.locale": "Use the given locale for CLI messages.",
 	"cli.opt.lockTimeout": "Wait for a workspace lock before failing.",
 	"cli.opt.logLevel": "Set log level: trace, debug, info, warn, or error.",
 	"cli.opt.prettyJson": "Write formatted JSON for people; not intended for line-oriented scripts.",
 	"cli.opt.quiet": "Suppress progress and informational output.",
-	"cli.opt.server": "Use the specified server for commands that support it.",
+	"cli.opt.server": "Direct target (below a positional URL, above the active server and SUCCAPP_SERVER); workspace synchronization requires the active server to match.",
 	"cli.opt.verbose": "Enable debug logging.",
 	"cli.opt.version": "Show version information and check for SuccApp CLI updates.",
-	"cli.opt.workspace": "Run as if SuccApp was started in the given workspace.",
+	"cli.opt.workspace": "Select the workspace without changing the process working directory; local input/output files remain relative to the launch directory.",
+	"cli.cmd.root.desc": "SuccApp CLI manages local workspaces, accesses servers, queries models, and operates databases.\n\nChoose a command group below, then run succapp <command> --help to continue one level at a time. Before executing a command, check its arguments, input rules, and effects.\n\nScripts and AI agents can use --json for structured help; use --pretty-json when reading JSON manually.\n\nFor first-time use or help choosing a command, read the CLI guide below. Check that it applies to your CLI and server versions; when offline, use an available matching manual.\n\nCheck both exit status and business results; kind=result can still contain conflicts, skipped items or truncation. --json does not cancel side effects such as opening a browser or writing data. See the guide below for output and exit-code conventions.\n\nDocumentation: CLI guide\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/basics/cli.md\nWeb: https://docs.succapp.com/ai-building/basics/cli",
 	"cli.cmd.auth.title": "Auth",
 	"cli.cmd.auth.summary": "login, logout, and inspect stored server auth",
-	"cli.cmd.auth.desc": "Login, logout, and inspect stored server auth.",
+	"cli.cmd.auth.desc": "Login, logout, and inspect stored server auth.\n\nUse login to establish and save authentication, status to inspect local records, and logout to remove them. Specify a server URL explicitly or use the active workspace server. CLI and IDE share these credentials.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Configure authentication\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/configure-auth.md\nWeb: https://docs.succapp.com/ai-building/workspace/configure-auth",
 	"cli.cmd.auth.login.summary": "Login to a server.",
-	"cli.cmd.auth.login.desc": "Login to a SuccApp server with OAuth2 or PAT and save local auth state.",
+	"cli.cmd.auth.login.desc": "Login to a SuccApp server with OAuth2 or PAT and save local auth state.\n\nOAuth2 opens a browser by default. In scripts without a browser, use --pat and supply the token through standard input. --oauth and --pat are mutually exclusive. Successful login stores credentials for subsequent commands.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Configure authentication\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/configure-auth.md\nWeb: https://docs.succapp.com/ai-building/workspace/configure-auth",
 	"cli.cmd.auth.login.oauth": "Use OAuth2 login. This is the default.",
 	"cli.cmd.auth.login.pat": "Use Personal Access Token login. Interactive terminals prompt for the token; piped input is read from stdin.",
 	"cli.cmd.auth.login.patPrompt": "Personal Access Token: ",
@@ -276,19 +279,20 @@
 	"cli.cmd.auth.login.loggedIn": "Logged in to {0}",
 	"cli.cmd.auth.login.loggedInAs": "Logged in to {0} as {1}",
 	"cli.cmd.auth.logout.summary": "Remove stored auth.",
-	"cli.cmd.auth.logout.desc": "Remove stored authentication information from the local auth settings.",
+	"cli.cmd.auth.logout.desc": "Remove stored authentication information from the local auth settings.\n\nWithout an explicit target, use the current server. --all removes local credentials for every server and cannot be combined with a positional URL. This does not revoke a server-issued PAT or remove workspace server configuration.",
 	"cli.cmd.auth.logout.all": "Remove stored auth for all servers.",
 	"cli.cmd.auth.logout.removedAllAuth": "Removed stored auth for all servers: {0}",
 	"cli.cmd.auth.logout.removedAuth": "Removed stored auth for {0}",
 	"cli.cmd.auth.logout.serverUrlTogether": "Do not pass a server URL together with --all.",
 	"cli.cmd.auth.logout.storedAuth": "No stored auth for {0}",
 	"cli.cmd.auth.status.summary": "Show stored auth status.",
-	"cli.cmd.auth.status.desc": "Show local stored authentication information for a server.",
+	"cli.cmd.auth.status.desc": "Show local stored authentication information for a server.\n\nThis reads saved local credentials without asking the server to validate them. token and refreshToken indicate presence, not secret values. If a subsequent request fails, check the server URL and sign in again.",
 	"cli.cmd.auth.status.noStoredOutput": "Server: {server}\nStored auth: {storedAuth}",
 	"cli.cmd.auth.status.output": "Server: {server}\nStored auth: {storedAuth}\nAuth type: {authType}\nUsername: {username}\nUser ID: {userId}\nToken: {token}\nRefresh token: {refreshToken}\nExpires at: {expiresAt}\nLast login at: {lastLoginAt}\nUpdated at: {updatedAt}",
+	"cli.cmd.auth.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
 	"cli.cmd.db.title": "Database",
 	"cli.cmd.db.summary": "inspect and operate server databases and data sources",
-	"cli.cmd.db.desc": "Inspect and operate server databases and data sources.",
+	"cli.cmd.db.desc": "Inspect and operate server databases and data sources.\n\nTo connect data, choose a connector under connector, then prepare and manage data sources under source. Use schema and table to inspect database structure. Each group lists only its direct children; run succapp db <group> --help to continue.\n\nUse query for physical tables and export to export data. For semantic model queries, see succapp model --help.\n\nexec, import, and data source write commands can modify server configuration or database data. Read the specific command's help and confirm the server, data source, and effects before executing it.\n\nRead the guide below when preparing a connection, and check that it applies to your server version.\n\nDocumentation: Connect data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\nWeb: https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.dataSource": "Data source",
 	"cli.cmd.db.connection": "Connection",
 	"cli.cmd.db.defaultSchema": "Logical default schema",
@@ -321,8 +325,8 @@
 	"cli.cmd.db.query.empty": "Query succeeded; 0 rows returned.",
 	"cli.cmd.db.tableOrQueryConflict": "Pass either <table> or --query/--query-file, not both.",
 	"cli.cmd.db.connector.title": "Database connector",
-	"cli.cmd.db.connector.summary": "discover available server database connectors",
-	"cli.cmd.db.connector.desc": "Discover the database connectors available on the active server and inspect their connector-specific configuration fields.",
+	"cli.cmd.db.connector.summary": "Inspect database connectors and their configuration fields.",
+	"cli.cmd.db.connector.desc": "Discover the database connectors available on the active server and inspect their connector-specific configuration fields.\n\nStart with list to obtain a connector ID, then use show to inspect its fields. Available connectors depend on the target server. Continue with succapp db source template to prepare a data source configuration.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Connect data sources\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\nWeb: https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.connector.connector": "Connector",
 	"cli.cmd.db.connector.displayName": "Display name",
 	"cli.cmd.db.connector.dbKind": "Database kind",
@@ -330,68 +334,68 @@
 	"cli.cmd.db.connector.defaultValue": "Default",
 	"cli.cmd.db.connector.secret": "secret",
 	"cli.cmd.db.connector.list.summary": "List database connectors available on the server.",
-	"cli.cmd.db.connector.list.desc": "List the database connectors available for datasource creation on the active server.",
+	"cli.cmd.db.connector.list.desc": "List the database connectors available for datasource creation on the active server.\n\nUse a returned connector ID with db connector show or db source template. Availability of a connector does not mean a data source has been configured or a database connection has been verified.",
 	"cli.cmd.db.connector.show.summary": "Show the configuration fields supported by a database connector.",
-	"cli.cmd.db.connector.show.desc": "Show common and connector-specific datasource configuration fields, safe defaults, and the JDBC URL template reported by the active server.",
+	"cli.cmd.db.connector.show.desc": "Show common and connector-specific datasource configuration fields, safe defaults, and the JDBC URL template reported by the active server.\n\nUse an ID returned by list for <connector>. Prepare values according to field types, required fields and secret fields. Replace template examples with real values and verify connectivity with db source test.",
 	"cli.cmd.db.connector.show.connector": "Database connector ID reported by db connector list.",
 	"cli.cmd.db.source.title": "Database source",
-	"cli.cmd.db.source.summary": "inspect and manage database sources",
-	"cli.cmd.db.source.desc": "Inspect and manage database sources.",
+	"cli.cmd.db.source.summary": "Inspect, test, and manage data sources.",
+	"cli.cmd.db.source.desc": "Inspect, test, and manage data sources on the server.\n\nUse list/show to inspect existing data sources and probe to verify connectivity and inspect the default schema. test accepts an existing data source or an unsaved configuration. Before creating a data source, obtain a template with template and read the input requirements for create.\n\ncreate, update, and remove change server data source configuration. test/probe attempt a real database connection. Read the specific command's help and confirm the target server and data source first.\n\nRead the guide below when preparing a connection, and check that it applies to your server version.\n\nDocumentation: Connect data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\nWeb: https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.*.config": "Read datasource configuration JSON from a file, or use - for stdin.",
 	"cli.cmd.db.source.*.test": "Test the connection before saving.",
 	"cli.cmd.db.source.list.summary": "List visible data sources.",
-	"cli.cmd.db.source.list.desc": "List data sources visible to the active SuccApp server session.",
+	"cli.cmd.db.source.list.desc": "List data sources visible to the active SuccApp server session.\n\nUse the returned data source identifiers with show, probe, schema, table and SQL commands. An empty list only means that the current server session returned no visible data sources.",
 	"cli.cmd.db.source.list.empty": "No data sources are available.",
 	"cli.cmd.db.source.show.summary": "Show a datasource configuration.",
-	"cli.cmd.db.source.show.desc": "Show a datasource configuration.",
+	"cli.cmd.db.source.show.desc": "Show a datasource configuration.\n\nUse an identifier returned by list for <datasource>. The JSON config field contains the configuration; password may be removed. Do not submit the entire result envelope or assume sanitized values form a complete update. This command does not test connectivity.",
 	"cli.cmd.db.source.probe.summary": "Validate an existing datasource and show its logical schema, database, and driver details.",
-	"cli.cmd.db.source.probe.desc": "Open and validate an existing datasource connection, then report its logical default schema, database product, normalized and full versions, and JDBC driver. JSON output also includes the sanitized datasource configuration.",
+	"cli.cmd.db.source.probe.desc": "Open and validate an existing datasource connection, then report its logical default schema, database product, normalized and full versions, and JDBC driver. JSON output also includes the sanitized datasource configuration.\n\nUse list to identify the data source first. Probing actually connects to the database. Success verifies this connection attempt, not permissions for subsequent queries or correctness of model configuration.",
 	"cli.cmd.db.source.probe.datasource": "Name of the existing datasource to probe.",
 	"cli.cmd.db.source.test.summary": "Test connectivity for an existing datasource or an unsaved JSON configuration.",
-	"cli.cmd.db.source.test.desc": "Validate connectivity for an existing datasource, or for a JSON configuration without saving it. Both modes return the logical default schema, database versions, and JDBC driver details.",
+	"cli.cmd.db.source.test.desc": "Validate connectivity for an existing datasource, or for a JSON configuration without saving it. Both modes return the logical default schema, database versions, and JDBC driver details.\n\nChoose exactly one of <datasource> and --config. --config reads a JSON file, or standard input when set to -. Submit the configuration object, not a CLI result envelope. Testing does not save configuration; use create or update to save it afterwards.",
 	"cli.cmd.db.source.test.datasource": "Name of the existing datasource to test.",
 	"cli.cmd.db.source.template.summary": "Generate a safe datasource JSON template for a server connector.",
-	"cli.cmd.db.source.template.desc": "Generate a datasource configuration template for a connector on the active server. The template uses the connector's defaults and never contains a password or other secret value.",
+	"cli.cmd.db.source.template.desc": "Generate a datasource configuration template for a connector on the active server. The template uses the connector's defaults and never contains a password or other secret value.\n\nUse a connector ID returned by db connector list. Human output is the configuration JSON itself; --json places it in config. Fill in real connection details, then test and create. This command does not create a data source.",
 	"cli.cmd.db.source.template.connector": "Database connector ID reported by db connector list.",
 	"cli.cmd.db.source.create.summary": "Create a datasource.",
-	"cli.cmd.db.source.create.desc": "Create a datasource from a JSON configuration. In a SuccApp workspace, AI agents should first read .agents/skills/succapp-docs/SKILL.md and follow its index to the datasource metadata and connector configuration documentation.",
+	"cli.cmd.db.source.create.desc": "Create a data source from JSON configuration on the selected server, saving the server's data source configuration.\n\nFirst use succapp db connector list/show to choose a connector and inspect its fields, then obtain a template with succapp db source template. Extract only config from the result, fill in the actual connection parameters, and submit it with --config. The entire result envelope is not valid creation input.\n\n--config is required and accepts a JSON file or - for stdin. --test checks connectivity before saving; it does not prove that later model queries or data permissions are valid.\n\nAfter saving, verify with succapp db source show on the same server and configuration name. An interrupted response does not prove that creation did not occur: inspect the current state before retrying. Returned configuration may omit password.\n\nRead the guide below before preparing a connection. In a SuccApp workspace, you can also read .agents/skills/succapp-docs/SKILL.md to find an applicable offline manual. Check that the documentation matches your server version.\n\nDocumentation: Connect data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\nWeb: https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.create.created": "Created data source: {0}",
 	"cli.cmd.db.source.update.summary": "Update a datasource.",
-	"cli.cmd.db.source.update.desc": "Update a datasource from a JSON configuration.",
+	"cli.cmd.db.source.update.desc": "Update a datasource from a JSON configuration.\n\nInspect the current configuration with show, then submit a configuration object through the required --config (file or - for standard input). Returned values may be sanitized, so check how secret fields must be supplied. --test tests the connection before saving. Updates affect the server directly; verify with show/probe, and inspect current state before retrying an interrupted request.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nSubmit the complete intended configuration, not a field patch. The accompanying server preserves a missing or empty password on update, but other omitted fields are not guaranteed to survive. Do not write a masked placeholder back as a new password.\n\nGuide: Connect data sources\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\nWeb: https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.update.updated": "Updated data source: {0}",
 	"cli.cmd.db.source.remove.summary": "Delete a datasource.",
-	"cli.cmd.db.source.remove.desc": "Delete a datasource after explicit confirmation.",
+	"cli.cmd.db.source.remove.desc": "Delete a datasource after explicit confirmation.\n\n--force is required to confirm removal of the server data source configuration. Check dependent models and tasks first. Removing the configuration does not delete physical database tables, but access depending on it may fail.",
 	"cli.cmd.db.source.remove.force": "Confirm datasource deletion.",
 	"cli.cmd.db.source.remove.dbSourceRemove": "Deleting a data source requires --force.",
 	"cli.cmd.db.source.remove.deleted": "Deleted data source: {0}",
 	"cli.cmd.db.schema.title": "Database schema",
-	"cli.cmd.db.schema.summary": "inspect database schemas",
-	"cli.cmd.db.schema.desc": "Inspect database schemas.",
+	"cli.cmd.db.schema.summary": "Inspect schemas in a data source.",
+	"cli.cmd.db.schema.desc": "Inspect database schemas.\n\nUse list to inspect schemas for a data source obtained from db source list. Continue with succapp db table --help for physical tables and columns.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Explore database data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-database-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-database-data",
 	"cli.cmd.db.schema.list.summary": "List schemas for a data source.",
-	"cli.cmd.db.schema.list.desc": "List schemas for a data source.",
+	"cli.cmd.db.schema.list.desc": "List schemas for a data source.\n\nUse a data source identifier from db source list; --catalog narrows the catalog. Use returned schema names for subsequent table inspection. Visibility depends on the connection and its permissions.",
 	"cli.cmd.db.schema.list.catalog": "Catalog",
 	"cli.cmd.db.schema.list.empty": "No schemas found for data source '{0}'.",
 	"cli.cmd.db.table.title": "Database table",
-	"cli.cmd.db.table.summary": "inspect database tables",
-	"cli.cmd.db.table.desc": "Inspect database tables.",
+	"cli.cmd.db.table.summary": "Inspect database tables and their structure.",
+	"cli.cmd.db.table.desc": "Inspect database tables.\n\nUse list to find physical tables and describe to inspect columns and table metadata. Identify the data source and schema first. These physical tables differ from the .tbl semantic models used by model commands.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Explore database data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-database-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-database-data",
 	"cli.cmd.db.table.list.summary": "List tables for a data source.",
-	"cli.cmd.db.table.list.desc": "List tables for a data source.",
+	"cli.cmd.db.table.list.desc": "List tables for a data source.\n\nIdentify the scope with db source list and db schema list, then filter table names with --table-name-contains. Before querying data, use describe to inspect column names and types.",
 	"cli.cmd.db.table.list.tableNameContains": "Filter tables by name. Supports * and ? wildcards.",
 	"cli.cmd.db.table.list.empty": "No tables are available.",
 	"cli.cmd.db.table.list.noMatches": "No tables matched the current filters.",
 	"cli.cmd.db.table.describe.summary": "Describe a database table.",
-	"cli.cmd.db.table.describe.desc": "Describe columns and metadata for a database table.",
+	"cli.cmd.db.table.describe.desc": "Describe columns and metadata for a database table.\n\nUse a table name returned by table list and specify --schema when needed. This reads structure rather than table rows; use db query to preview data.\n\nA table can be written as schema.table. With explicit --schema, <table> is used as the complete table name; supply an unqualified name to avoid double qualification.",
 	"cli.cmd.db.table.describe.schema": "Schema name.",
 	"cli.cmd.db.*.file": "Read SQL from a file.",
 	"cli.cmd.db.*.schema": "SQL execution schema.",
 	"cli.cmd.db.*.timeout": "SQL timeout in seconds. Defaults to 30.",
 	"cli.cmd.db.query.summary": "Execute a read-only SQL query.",
-	"cli.cmd.db.query.desc": "Execute SQL through Dev Tool v2. SuccApp CLI only allows read-only queries.",
+	"cli.cmd.db.query.desc": "Execute a read-only SQL query on the specified data source. Use succapp db source list to obtain a visible data source identifier, and succapp db table list/describe to inspect tables.\n\nProvide at most one of the <sql> positional argument and --file. When both are omitted, read SQL from stdin. --timeout is in seconds and defaults to 30.\n\nQueries are for preview: a limited result must not be assumed to contain all data. For a full export, see succapp db export --help.\n\nThis command is not used for data writes. Before writing data, read succapp db exec --help and confirm its effects.\n\nThe accompanying server defaults to a 100-row preview with a 1000-row cap. Actual behavior depends on the target server and returned truncation information. Use the corresponding export command for full data.\n\n--max-rows=0 uses the server default; it does not mean unlimited rows.",
 	"cli.cmd.db.query.maxRows": "Maximum returned row count.",
 	"cli.cmd.db.query.nonReadOnlySql": "db query only allows read-only SQL. Use db exec for write or schema changes; add --force only after confirming the impact.",
 	"cli.cmd.db.query.sqlOrFileConflict": "Pass SQL either as <sql> or --file, not both.",
 	"cli.cmd.db.exec.summary": "Execute any SQL.",
-	"cli.cmd.db.exec.desc": "Execute SQL through Dev Tool v2. Write or schema changes require explicit confirmation.",
+	"cli.cmd.db.exec.desc": "Execute SQL and return result sets or update counts; this may change database data or structure.\n\nChoose at most one of positional <sql> and --file; if neither is supplied, read standard input. The default timeout is 30 seconds. SQL classified as dangerous by the server requires --force. Absence of that requirement does not mean a statement is read-only. Confirm write effects first and inspect database state before retrying after timeout or disconnection.\n\nThe accompanying server defaults to a 100-row preview with a 1000-row cap. Actual behavior depends on the target server and returned truncation information. Use the corresponding export command for full data.\n\n--max-rows=0 uses the server default; it does not mean unlimited rows.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Modify database data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/modify-database-data.md\nWeb: https://docs.succapp.com/ai-building/data/modify-database-data",
 	"cli.cmd.db.exec.maxRows": "Limit returned rows for result sets.",
 	"cli.cmd.db.exec.force": "Confirm SQL marked dangerous by safety analysis.",
 	"cli.cmd.db.exec.dangerousSql": "Dangerous SQL was blocked. Review the impact before rerunning with --force.{0}",
@@ -399,53 +403,61 @@
 	"cli.cmd.db.exec.fullTableData": "full-table data mutation",
 	"cli.cmd.db.exec.schemaMutation": "schema mutation",
 	"cli.cmd.db.import.summary": "Import CSV data into a table.",
-	"cli.cmd.db.import.desc": "Import CSV data into a database table.",
+	"cli.cmd.db.import.desc": "Import CSV data into a database table.\n\nUse --input for a UTF-8 CSV file or - for standard input, with column names in the first row. append is the default. Both truncate and replace currently clear the target table before importing; they are not primary-key upserts.\n\n--dry-run only parses and counts CSV rows; it does not validate database constraints or perform writes. importedRows counts CSV data rows rather than independently verified inserted rows. Import changes the database; check database state after interruption before appending again.\n\nA table can be written as schema.table. With explicit --schema, <table> is used as the complete table name; supply an unqualified name to avoid double qualification.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Import and export data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/import-export-data.md\nWeb: https://docs.succapp.com/ai-building/data/import-export-data",
 	"cli.cmd.db.import.input": "Read table data CSV from a file, or use - for stdin.",
 	"cli.cmd.db.import.mode": "Import mode. Defaults to append; truncate and replace must be passed explicitly.",
-	"cli.cmd.db.import.dryRun": "Validate import without writing rows.",
+	"cli.cmd.db.import.dryRun": "Parse and count CSV rows without writing or validating actual database constraints.",
 	"cli.cmd.db.import.schema": "Table schema.",
 	"cli.cmd.db.export.summary": "Export table data or a query result as CSV.",
-	"cli.cmd.db.export.desc": "Export table data or a query result as CSV.",
+	"cli.cmd.db.export.desc": "Export table data or a query result as CSV.\n\nChoose exactly one of <table>, --query and --query-file, and specify a local CSV file with --output. Overwriting an existing file requires --force. Query conditions and server permissions still apply; check the output file and reported size after completion.\n\nA table can be written as schema.table. With explicit --schema, <table> is used as the complete table name; supply an unqualified name to avoid double qualification.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Import and export data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/import-export-data.md\nWeb: https://docs.succapp.com/ai-building/data/import-export-data",
 	"cli.cmd.db.export.query": "Export a query result instead of table data.",
 	"cli.cmd.db.export.queryFile": "Read export query SQL from a file.",
 	"cli.cmd.db.export.schema": "Table schema or SQL execution schema.",
 	"cli.cmd.db.export.output": "Write CSV output to a local file.",
 	"cli.cmd.db.export.force": "Overwrite the output file if it already exists.",
 	"cli.cmd.db.export.exportedData": "Exported data to {0}",
+	"cli.cmd.db.*.datasource": "A data source identifier returned by db source list, not a connector ID.",
+	"cli.cmd.db.*.sql": "SQL text; mutually exclusive with --file. If both are omitted, read standard input.",
+	"cli.cmd.db.*.table": "A table name returned by db table list; schema.table is supported when --schema is omitted.",
+	"cli.cmd.db.source.*.datasource": "A data source identifier returned by db source list, not a connector ID.",
+	"cli.cmd.db.schema.*.datasource": "A data source identifier returned by db source list, not a connector ID.",
+	"cli.cmd.db.table.*.datasource": "A data source identifier returned by db source list, not a connector ID.",
+	"cli.cmd.db.table.*.schema": "A schema returned by db schema list; omitted scope is resolved by the data source.",
+	"cli.cmd.db.table.*.table": "A table name returned by db table list; schema.table is supported when --schema is omitted.",
 	"cli.cmd.server.title": "Server",
 	"cli.cmd.server.summary": "inspect and operate the target SuccApp server",
-	"cli.cmd.server.desc": "Inspect and operate the target SuccApp server.",
+	"cli.cmd.server.desc": "Inspect and operate the target SuccApp server.\n\nThese commands access the target server directly without cloning a project. Select the target with --server or the active workspace server, and authenticate with auth login. File, settings, script and administrative writes affect the server directly.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: System diagnostics\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\nWeb: https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.serverNotConfigured": "Server is not configured for this workspace: {0}",
 	"cli.cmd.server.serverReachable": "Server reachable: {0}",
 	"cli.cmd.server.ping.summary": "Check server reachability.",
-	"cli.cmd.server.ping.desc": "Check whether the SuccApp Dev Tool v2 ping endpoint is reachable.",
+	"cli.cmd.server.ping.desc": "Check whether the SuccApp Dev Tool v2 ping endpoint is reachable.\n\nA server URL may be supplied directly. Success means the ping endpoint is reachable, not that authentication, business permissions or database access are valid. Continue with server info for diagnostics.",
 	"cli.cmd.server.info.summary": "Show server information.",
-	"cli.cmd.server.info.desc": "Show server information and metadata versions.",
+	"cli.cmd.server.info.desc": "Show server information and metadata versions.\n\nShows main information by default. Select sections with --scope or expand with --all. This confirms the environment and version without upgrading it. Use --json for structured fields in scripts.",
 	"cli.cmd.server.info.scope": "Show only the selected scope. Repeat or use comma-separated values: product, sys, metadata, inspect, jvm, env, all.",
 	"cli.cmd.server.info.all": "Show all information scopes.",
 	"cli.cmd.server.info.raw": "Output the raw server detail response.",
 	"cli.cmd.server.cache.title": "Server cache",
 	"cli.cmd.server.cache.summary": "manage server cache",
-	"cli.cmd.server.cache.desc": "Manage server cache.",
+	"cli.cmd.server.cache.desc": "Manage server cache.\n\nInspect names and usage with list before cleaning individual entries with clean. Cleaning affects running server caches; --all covers all system caches.",
 	"cli.cmd.server.cache.list.summary": "List server cache entries.",
-	"cli.cmd.server.cache.list.desc": "List server-side system cache entries (count, disk/memory usage, hit rate).",
+	"cli.cmd.server.cache.list.desc": "List server-side system cache entries (count, disk/memory usage, hit rate).\n\nValues reflect cache state at query time; hit rates and other statistics change during operation. Use returned names when cleaning rather than guessing identifiers.",
 	"cli.cmd.server.cache.list.empty": "No server cache entries.",
 	"cli.cmd.server.cache.clean.summary": "Clean server cache.",
-	"cli.cmd.server.cache.clean.desc": "Clean a server-side system cache entry by <name>, or all caches with --all.",
+	"cli.cmd.server.cache.clean.desc": "Clean a server-side system cache entry by <name>, or all caches with --all.\n\nChoose exactly one of <name> and --all; no additional --force is required. Cleaning invalidates caches and subsequent access may reload data. Inspect list before and after the operation.",
 	"cli.cmd.server.cache.clean.all": "Clean all server cache entries.",
 	"cli.cmd.server.cache.clean.cleaned": "Server cache cleaned: {1} ({0})",
 	"cli.cmd.server.cluster.title": "Server cluster",
 	"cli.cmd.server.cluster.summary": "inspect server cluster nodes",
-	"cli.cmd.server.cluster.desc": "Inspect cluster membership, health, network state, and runtime diagnostics.",
+	"cli.cmd.server.cluster.desc": "Inspect cluster membership, health, network state, and runtime diagnostics.\n\nObtain node IDs with list, then inspect a node with show. Membership and diagnostic samples can change as nodes join or leave.",
 	"cli.cmd.server.cluster.list.summary": "List server cluster nodes.",
-	"cli.cmd.server.cluster.list.desc": "List the same cluster node data used by the server system-settings page.",
+	"cli.cmd.server.cluster.list.desc": "List the same cluster node data used by the server system-settings page.\n\nUse returned node IDs with cluster show. Check availability and health before further diagnostics; an unreachable listed node is not a healthy node.\n\n--watch refreshes continuously until Ctrl+C; --interval requires --watch. --watch does not support --json; scripts should repeat one-shot JSON queries.",
 	"cli.cmd.server.cluster.list.health": "Only include nodes with this health severity: ok, warning, error, or unknown.",
 	"cli.cmd.server.cluster.list.watch": "Continuously refresh the cluster status until interrupted.",
 	"cli.cmd.server.cluster.list.interval": "Set the watch refresh interval in milliseconds (3000 to 60000). Requires --watch.",
 	"cli.cmd.server.cluster.list.empty": "No cluster nodes match the current filter.",
 	"cli.cmd.server.cluster.list.updatedAt": "Updated: {0}",
 	"cli.cmd.server.cluster.show.summary": "Show one server cluster node.",
-	"cli.cmd.server.cluster.show.desc": "Show an exact cluster node by ID using the same scoped information layout as server info.",
+	"cli.cmd.server.cluster.show.desc": "Show an exact cluster node by ID using the same scoped information layout as server info.\n\nUse a node ID returned by cluster list. --scope or --all expands the information requested. A node can go offline between requests; refresh the node list after a failure.",
 	"cli.cmd.server.cluster.show.scope": "Show only the selected human-output details. Repeat or use comma-separated values: product, sys, inspect, jvm, env, all.",
 	"cli.cmd.server.cluster.show.all": "Show all human-output detail scopes.",
 	"cli.cmd.server.cluster.out.name": "Name",
@@ -476,23 +488,23 @@
 	"cli.cmd.server.cluster.out.lastSentAt": "Last sent",
 	"cli.cmd.server.thread.title": "Server threads",
 	"cli.cmd.server.thread.summary": "inspect JVM threads",
-	"cli.cmd.server.thread.desc": "Inspect JVM thread snapshots and request cancellation of registered product tasks.",
+	"cli.cmd.server.thread.desc": "Inspect JVM thread snapshots and request cancellation of registered product tasks.\n\nUse list for a quick filter, show for one thread, dump for full stacks, and top for sampled analysis. cancel only requests cooperative cancellation of registered product tasks; it cannot terminate arbitrary JVM threads.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: System diagnostics\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\nWeb: https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.thread.*.state": "Only include this JVM state: new, runnable, blocked, waiting, timed-waiting, or terminated.",
 	"cli.cmd.server.thread.*.working": "Only include threads that are currently doing work.",
 	"cli.cmd.server.thread.*.sql": "Only include threads that are currently executing SQL.",
 	"cli.cmd.server.thread.list.summary": "List JVM threads.",
-	"cli.cmd.server.thread.list.desc": "List JVM thread summaries without full stack traces.",
+	"cli.cmd.server.thread.list.desc": "List JVM thread summaries without full stack traces.\n\nFilter by state, registered work or SQL execution, and select a node with --cluster. Thread IDs are meaningful only for the corresponding node and time. Use show or dump for full context.",
 	"cli.cmd.server.thread.list.cluster": "Run the query on one cluster node.",
 	"cli.cmd.server.thread.list.empty": "No JVM threads match the current filter.",
 	"cli.cmd.server.thread.dump.summary": "Capture a JVM thread dump.",
-	"cli.cmd.server.thread.dump.desc": "Capture matching JVM threads with untruncated stack traces.",
+	"cli.cmd.server.thread.dump.desc": "Capture matching JVM threads with untruncated stack traces.\n\nNarrow the scope with --state, --working or --sql, and select a node with --cluster. Output is a single snapshot. Use top or compare multiple snapshots to investigate sustained activity.",
 	"cli.cmd.server.thread.dump.cluster": "Capture the thread dump from one cluster node.",
 	"cli.cmd.server.thread.dump.deadlocks.none": "Deadlocks: none",
 	"cli.cmd.server.thread.dump.deadlocks.found": "Deadlocks: {0}",
 	"cli.cmd.server.thread.dump.waitingLock": "waiting on {0}",
 	"cli.cmd.server.thread.dump.waitingLockOwned": "waiting on {0}, owned by thread #{1}",
 	"cli.cmd.server.thread.top.summary": "Sample JVM thread hotspots.",
-	"cli.cmd.server.thread.top.desc": "Poll raw CPU, thread, memory, and GC samples, then analyze them locally without retaining a server-side report.",
+	"cli.cmd.server.thread.top.desc": "Poll raw CPU, thread, memory, and GC samples, then analyze them locally without retaining a server-side report.\n\n--duration controls total time, --interval the sampling interval, and --refresh progress refresh. Analysis covers only the observation window. Check failed nodes and sample completeness; missing samples are not zero load.",
 	"cli.cmd.server.thread.top.cluster": "Sample one cluster node, or use all to poll every current member concurrently.",
 	"cli.cmd.server.thread.top.duration": "Set the client-side analysis window from 1s to 20s; use an ms or s suffix.",
 	"cli.cmd.server.thread.top.interval": "Set each server sampling window from 200ms to 2s; the analysis window must contain at least two samples.",
@@ -536,12 +548,12 @@
 	"cli.cmd.server.thread.top.out.gcCount": "Collections",
 	"cli.cmd.server.thread.top.out.gcTime": "GC time",
 	"cli.cmd.server.thread.show.summary": "Show one JVM thread.",
-	"cli.cmd.server.thread.show.desc": "Show the current thread snapshot, authorized SQL details, and full stack trace.",
+	"cli.cmd.server.thread.show.desc": "Show the current thread snapshot, authorized SQL details, and full stack trace.\n\nObtain the thread ID from list and keep the same --cluster target. The thread may already have ended or changed tasks. For cancellation, read cancelSerial from a fresh snapshot and check cancel requirements.",
 	"cli.cmd.server.thread.show.cluster": "Read the thread from one cluster node.",
 	"cli.cmd.server.thread.show.stack": "Stack:",
 	"cli.cmd.server.thread.show.stackEmpty": "  (stack is no longer available)",
 	"cli.cmd.server.thread.cancel.summary": "Request cancellation of a JVM thread task.",
-	"cli.cmd.server.thread.cancel.desc": "Request cooperative cancellation of the registered product task that still matches the cancel serial.",
+	"cli.cmd.server.thread.cancel.desc": "Request cooperative cancellation of the registered product task that still matches the cancel serial.\n\nProvide a fresh --cancel-serial and --force, targeting the same node used by show. Success means cancellation was requested, not that the task ended immediately. Recheck state afterwards; do not blindly retry against a new task if the serial changes.",
 	"cli.cmd.server.thread.cancel.cancelSerial": "Require the current cancel serial returned by thread list or show.",
 	"cli.cmd.server.thread.cancel.cluster": "Cancel the task on one cluster node.",
 	"cli.cmd.server.thread.cancel.force": "Confirm the cooperative cancellation request.",
@@ -562,13 +574,13 @@
 	"cli.cmd.server.thread.out.logAvailable": "Log available",
 	"cli.cmd.server.techLog.title": "Server technical log",
 	"cli.cmd.server.techLog.summary": "inspect and manage server technical logs",
-	"cli.cmd.server.techLog.desc": "Inspect technical logs and manage runtime logger levels. These commands require access to the system-settings console.",
+	"cli.cmd.server.techLog.desc": "Inspect technical logs and manage runtime logger levels. These commands require access to the system-settings console.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nUse list for log files, tail to read or follow the current log, download to save a file, and level to manage logging levels. Select the intended node in a cluster and limit reads to the diagnostic context needed.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: System diagnostics\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\nWeb: https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.techLog.*.cluster": "Read from a named cluster node; omit for the current HTTP node. Find node names with 'succapp server cluster list'.",
 	"cli.cmd.server.techLog.list.summary": "List technical log files.",
-	"cli.cmd.server.techLog.list.desc": "List the same .log files shown by the server system-settings console. Requires console view permission.",
+	"cli.cmd.server.techLog.list.desc": "List the same .log files shown by the server system-settings console. Requires console view permission.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nUse returned filenames with download and keep the same node. This lists server logs, not local CLI logs.",
 	"cli.cmd.server.techLog.list.empty": "No technical log files are available on this node.",
 	"cli.cmd.server.techLog.tail.summary": "Read the technical log tail.",
-	"cli.cmd.server.techLog.tail.desc": "Read the active technical log using the system-settings cursor protocol. Requires console view permission. One-shot JSON keeps content as plain log text.",
+	"cli.cmd.server.techLog.tail.desc": "Read the active technical log using the system-settings cursor protocol. Requires console view permission. One-shot JSON keeps content as plain log text.\n\nSet POSITION and CURSOR_FILE from position and logFile in the same tail response and keep the same target node; these are not arbitrary line numbers or file names.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nReads once by default; --follow polls until stopped with Ctrl+C. To resume, pass --from and --log-file from the previous result together. Do not reuse a cursor for another node or a rotated file.\n\n--from and --log-file must be paired and cannot be combined with explicit --lines. --interval requires --follow. --follow does not support --json; scripts can resume using one-shot JSON results.",
 	"cli.cmd.server.techLog.tail.lines": "Keep this many lines from the initial log fragment (1 to 5000, default 200).",
 	"cli.cmd.server.techLog.tail.from": "Continue from a previous one-shot JSON result; requires --log-file.",
 	"cli.cmd.server.techLog.tail.logFile": "Use the log file from a previous one-shot JSON result; requires --from.",
@@ -576,7 +588,7 @@
 	"cli.cmd.server.techLog.tail.interval": "Set the follow polling interval in milliseconds (500 to 60000). Requires --follow.",
 	"cli.cmd.server.techLog.tail.retry": "Temporary network error; retry {0} in {1} ms.",
 	"cli.cmd.server.techLog.download.summary": "Download a technical log file.",
-	"cli.cmd.server.techLog.download.desc": "Download a file returned by 'succapp server tech-log list'. Requires console log export permission.",
+	"cli.cmd.server.techLog.download.desc": "Download a file returned by 'succapp server tech-log list'. Requires console log export permission.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nUse a filename from tech-log list on the same node. --output specifies the local file; overwriting requires --force. Downloading does not clear or rotate server logs.",
 	"cli.cmd.server.techLog.download.cluster": "Download from a named cluster node; omit for the current HTTP node. Find node names with 'succapp server cluster list'.",
 	"cli.cmd.server.techLog.download.file": "Use the exact file name returned by 'succapp server tech-log list'.",
 	"cli.cmd.server.techLog.download.output": "Write the log to this local file.",
@@ -584,23 +596,23 @@
 	"cli.cmd.server.techLog.download.downloaded": "Downloaded technical log {0} to {1}",
 	"cli.cmd.server.techLog.level.title": "Technical log level",
 	"cli.cmd.server.techLog.level.summary": "inspect and manage logger levels",
-	"cli.cmd.server.techLog.level.desc": "Inspect, persist, hot-apply, and reset logger levels. These commands require system-settings console view permission.",
+	"cli.cmd.server.techLog.level.desc": "Inspect, persist, hot-apply, and reset logger levels. These commands require system-settings console view permission.\n\nUse list to compare saved and effective levels, set to change a logger, reset to restore inheritance, and apply-to-cluster to distribute the full configuration. Restore appropriate levels after temporary diagnostics.",
 	"cli.cmd.server.techLog.level.*.cluster": "Modify a named cluster node; omit for the current HTTP node. Find node names with 'succapp server cluster list'.",
 	"cli.cmd.server.techLog.level.list.summary": "List logger levels.",
-	"cli.cmd.server.techLog.level.list.desc": "List persisted and effective logger levels on the target node. Requires console view permission.",
+	"cli.cmd.server.techLog.level.list.desc": "List persisted and effective logger levels on the target node. Requires console view permission.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nCompare explicit configuration with effective levels to understand inheritance. Confirm the target node in a cluster; one node does not establish consistency across the cluster.",
 	"cli.cmd.server.techLog.level.list.cluster": "Read from a named cluster node; omit for the current HTTP node. Find node names with 'succapp server cluster list'.",
 	"cli.cmd.server.techLog.level.set.summary": "Set a logger level.",
-	"cli.cmd.server.techLog.level.set.desc": "Persist and hot-apply one logger level on the target node. Requires console view permission.",
+	"cli.cmd.server.techLog.level.set.desc": "Persist and hot-apply one logger level on the target node. Requires console view permission.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nTRACE and DEBUG require --force and may increase log volume and runtime overhead. Verify with level list afterwards. Use reset to restore inheritance; cluster distribution is a separate apply-to-cluster operation.",
 	"cli.cmd.server.techLog.level.set.force": "Confirm TRACE or DEBUG after reviewing the operational impact.",
 	"cli.cmd.server.techLog.level.set.logger": "Use an exact named logger; root and wildcards are not allowed.",
 	"cli.cmd.server.techLog.level.set.level": "Use TRACE, DEBUG, INFO, or ERROR. Values are case-sensitive.",
 	"cli.cmd.server.techLog.level.set.updated": "Updated logger {0} to {1}",
 	"cli.cmd.server.techLog.level.reset.summary": "Reset a named logger level.",
-	"cli.cmd.server.techLog.level.reset.desc": "Remove a logger's explicit level so it inherits from its parent. Requires console view permission.",
+	"cli.cmd.server.techLog.level.reset.desc": "Remove a logger's explicit level so it inherits from its parent. Requires console view permission.\n\nBefore using examples, set NODE to a node ID from server cluster list and LOG_FILE to a file name from tech-log list for that node. Keep variables double-quoted so spaces and shell metacharacters remain part of the argument.\n\nRemove explicit configuration by logger name. The effective level depends on its parent, so reset does not mean disabling logs. Inspect level list afterwards.",
 	"cli.cmd.server.techLog.level.reset.logger": "Use an exact named logger; root and wildcards are not allowed.",
 	"cli.cmd.server.techLog.level.reset.reset": "Reset logger level: {0}",
 	"cli.cmd.server.techLog.level.apply.summary": "Apply logger levels to the cluster.",
-	"cli.cmd.server.techLog.level.apply.desc": "Submit the current HTTP node's complete Logback configuration to reachable peers. Requires console view permission. Success confirms submission only, not per-node completion.",
+	"cli.cmd.server.techLog.level.apply.desc": "Submit the current HTTP node's complete Logback configuration to reachable peers. Requires console view permission. Success confirms submission only, not per-node completion.\n\n--force is required. This distributes the current HTTP node's complete Logback configuration, not just the last modified logger. Inspect the source configuration first, then check effective levels on each node after submission.",
 	"cli.cmd.server.techLog.level.apply.force": "Confirm replacing the complete Logback configuration on reachable cluster peers.",
 	"cli.cmd.server.techLog.level.apply.applied": "The Logback configuration was submitted to the cluster.",
 	"cli.cmd.server.techLog.out.file": "File",
@@ -612,17 +624,17 @@
 	"cli.cmd.server.techLog.out.effectiveLevel": "Effective",
 	"cli.cmd.server.proj.title": "Server project",
 	"cli.cmd.server.proj.summary": "inspect server projects",
-	"cli.cmd.server.proj.desc": "Inspect server projects.",
+	"cli.cmd.server.proj.desc": "Inspect server projects.\n\nUse list to discover visible projects and create to create a server project. Download one locally with workspace project clone.",
 	"cli.cmd.server.proj.list.summary": "List server projects.",
-	"cli.cmd.server.proj.list.desc": "List projects visible on a server.",
+	"cli.cmd.server.proj.list.desc": "List projects visible on a server.\n\nUse returned project names to locate files or clone a project. Visibility depends on the current user; an absent entry does not necessarily mean the project does not exist.",
 	"cli.cmd.server.proj.list.empty": "No visible projects found.",
 	"cli.cmd.server.proj.create.summary": "Create a server project.",
-	"cli.cmd.server.proj.create.desc": "Create a metadata project on a server.",
+	"cli.cmd.server.proj.create.desc": "Create a metadata project on a server.\n\nProvide a new project name and optionally --desc. Creation affects the server directly. Verify with project list, then clone for local development. After an interrupted response, check whether the project was already created.",
 	"cli.cmd.server.proj.create.descOption": "Set the project description.",
 	"cli.cmd.server.proj.create.created": "Created server project: {0}",
 	"cli.cmd.server.file.title": "Server file",
 	"cli.cmd.server.file.summary": "inspect and operate server metadata files",
-	"cli.cmd.server.file.desc": "Inspect and operate server metadata files.",
+	"cli.cmd.server.file.desc": "Inspect and operate server metadata files.\n\nLocate paths with list/search/locate, then inspect them with info/show/history. create/update/remove change remote metadata directly without updating a local workspace. Obtain the revision before updates or deletion and verify afterwards.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Find metadata files\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/project/find-metafile.md\nWeb: https://docs.succapp.com/ai-building/project/find-metafile",
 	"cli.cmd.server.file.*.file": "Read content from a local file.",
 	"cli.cmd.server.file.*.stdin": "Read content from stdin.",
 	"cli.cmd.server.file.badValue": "Invalid value for {0}: {1}",
@@ -636,10 +648,10 @@
 	"cli.cmd.server.file.success": "{0} succeeded: {1}",
 	"cli.cmd.server.file.unknownServerFile": "Unknown server file error.",
 	"cli.cmd.server.file.list.summary": "List server files.",
-	"cli.cmd.server.file.list.desc": "List direct children of a server metadata directory.",
+	"cli.cmd.server.file.list.desc": "List direct children of a server metadata directory.\n\nUse a server metadata directory path; results contain direct children. Use file search for recursive discovery or name filtering. Quote paths containing spaces.",
 	"cli.cmd.server.file.list.empty": "Directory is empty: {0}",
 	"cli.cmd.server.file.search.summary": "Search server files.",
-	"cli.cmd.server.file.search.desc": "Search readable server metadata files by full path or by combinable project, parent-directory, and file-name filters.",
+	"cli.cmd.server.file.search.desc": "Search readable server metadata files by full path or by combinable project, parent-directory, and file-name filters.\n\nUse returned full paths with info/show/download. Combining filters narrows the scope, and --limit bounds results. Refine filters when results are empty or reach the limit rather than concluding a resource does not exist.",
 	"cli.cmd.server.file.search.url": "Optional server URL. A lone non-URL argument is treated as <query>.",
 	"cli.cmd.server.file.search.query": "Starts with '/': full path or path glob. Contains '*' or '?': file name glob. Otherwise searches file metadata by keyword.",
 	"cli.cmd.server.file.search.path": "Search by an absolute metadata path glob; a project root searches recursively. Can be combined with a keyword <query>, but not with a path <query>, --project, --parent-dir, or --name.",
@@ -661,9 +673,9 @@
 	"cli.cmd.server.file.search.warningDetails": "Content was not checked; use --json for full details.",
 	"cli.cmd.server.recyclebin.title": "Server recycle bin",
 	"cli.cmd.server.recyclebin.summary": "Search files in the server recycle bin",
-	"cli.cmd.server.recyclebin.desc": "Search and inspect deleted files that are visible in server project recycle bins.",
+	"cli.cmd.server.recyclebin.desc": "Search and inspect deleted files that are visible in server project recycle bins.\n\nUse search within a project to inspect deleted resources, paths and deletion times. This group queries the recycle bin; it does not restore or permanently purge resources.",
 	"cli.cmd.server.recyclebin.search.summary": "Search server recycle bin files.",
-	"cli.cmd.server.recyclebin.search.desc": "Search visible files in a project recycle bin by keyword, path, type, or delete time.",
+	"cli.cmd.server.recyclebin.search.desc": "Search visible files in a project recycle bin by keyword, path, type, or delete time.\n\nSpecify a project, combine filters as needed, and use --limit to bound results. These are recycle-bin records; their paths do not prove that live files exist. Use the product restoration workflow when recovery is needed.",
 	"cli.cmd.server.recyclebin.search.url": "Optional server URL. A lone non-URL first argument is treated as <project>.",
 	"cli.cmd.server.recyclebin.search.project": "Project name whose recycle bin should be searched.",
 	"cli.cmd.server.recyclebin.search.query": "Search keyword, full metadata path, or path glob.",
@@ -674,86 +686,129 @@
 	"cli.cmd.server.recyclebin.search.empty": "No matching recycle bin files in project {0}.",
 	"cli.cmd.server.recyclebin.search.hasMore": "Only {0} recycle bin files are shown; add a type, delete time range, or more specific keyword to narrow the search.",
 	"cli.cmd.server.file.locate.summary": "Locate a server file by metadata ID.",
-	"cli.cmd.server.file.locate.desc": "Resolve a metadata ID to the current server file path.",
+	"cli.cmd.server.file.locate.desc": "Resolve a metadata ID to the current server file path.\n\n<id> is a server metadata ID, not a filename or local path. --url returns a view or edit page address. Use the resolved path with info/show afterwards.",
 	"cli.cmd.server.file.locate.url": "Only print the server view or edit URL.",
 	"cli.cmd.server.file.locate.viewUrl": "View URL: {0}",
 	"cli.cmd.server.file.locate.editUrl": "Edit URL: {0}",
 	"cli.cmd.server.file.info.summary": "Show server file information.",
-	"cli.cmd.server.file.info.desc": "Show server-side metadata for a file or directory.",
+	"cli.cmd.server.file.info.desc": "Show server-side metadata for a file or directory.\n\nUse a server metadata path. The returned revision can be passed as --expected-revision to update/remove. Prepare changes from current content; reread and compare after a revision conflict.",
 	"cli.cmd.server.file.show.summary": "Show server file content.",
-	"cli.cmd.server.file.show.desc": "Write server file content to stdout. Omit --json to inspect readable text; --json wraps content as Base64 for scripts.",
+	"cli.cmd.server.file.show.desc": "Write server file content to stdout. Omit --json to inspect readable text; --json wraps content as Base64 for scripts.\n\nReads current content by default; --revision reads a historical version. --upgrade-content requests upgraded response content without saving it back to the server. Use download to save a local file.",
 	"cli.cmd.server.file.show.revision": "Read a server file revision.",
 	"cli.cmd.server.file.show.upgradeContent": "Return upgraded metadata JSON content when supported.",
 	"cli.cmd.server.file.download.summary": "Download server file content.",
-	"cli.cmd.server.file.download.desc": "Download server file content to a local file.",
+	"cli.cmd.server.file.download.desc": "Download server file content to a local file.\n\n--output is required; overwriting an existing file needs --force. --revision selects a version and --upgrade-content affects only downloaded content. Downloading does not create a workspace synchronization baseline.",
 	"cli.cmd.server.file.download.revision": "Download a server file revision.",
 	"cli.cmd.server.file.download.upgradeContent": "Download upgraded metadata JSON content when supported.",
 	"cli.cmd.server.file.download.output": "Write content to a local file.",
 	"cli.cmd.server.file.download.force": "Overwrite the local output file if it exists.",
 	"cli.cmd.server.file.download.downloaded": "Downloaded {0} to {1}",
 	"cli.cmd.server.file.open.summary": "Open the server file page.",
-	"cli.cmd.server.file.open.desc": "Open the server view or edit page in the system browser, or return its URL without opening the browser.",
+	"cli.cmd.server.file.open.desc": "Open the server view or edit page in the system browser, or return its URL without opening the browser.\n\nOpens a view page by default; --edit selects editing. Use --no-open in scripts or headless environments to return only the URL. This command does not upload content.",
 	"cli.cmd.server.file.open.edit": "Open the server edit page instead of the view page.",
 	"cli.cmd.server.file.open.noOpen": "Return the page URL without launching the system browser.",
 	"cli.cmd.server.file.open.path": "Absolute server metadata path. The URL is constructed without checking whether the file exists.",
 	"cli.cmd.server.file.open.openedEdit": "Opened server edit page: {0}",
 	"cli.cmd.server.file.open.openedView": "Opened server view page: {0}",
 	"cli.cmd.server.file.history.summary": "Show server file history.",
-	"cli.cmd.server.file.history.desc": "Show server-side file history for a server file path.",
+	"cli.cmd.server.file.history.desc": "Show server-side file history for a server file path.\n\nUse a server path; --limit bounds the number of entries. Results are versions saved by the server, and their revisions can be used with show/download. This is not local Git history.",
 	"cli.cmd.server.file.history.limit": "Limit the number of history records.",
 	"cli.cmd.server.file.create.summary": "Create a server file.",
-	"cli.cmd.server.file.create.desc": "Create a server file and fail if it already exists.",
+	"cli.cmd.server.file.create.desc": "Create a server file and fail if it already exists.\n\nChoose exactly one of --file and --stdin. Content is written directly to the server path. create cannot overwrite an existing target; use update with revision protection. After interruption, check info/show before retrying.",
 	"cli.cmd.server.file.update.summary": "Update a server file.",
-	"cli.cmd.server.file.update.desc": "Update an existing server file with revision protection by default.",
+	"cli.cmd.server.file.update.desc": "Update an existing server file with revision protection by default.\n\nChoose exactly one of --file and --stdin, and exactly one of --expected-revision and --force. Prefer the revision returned by info; reread and compare after conflicts. --force bypasses revision protection. Verify with show after writing.",
 	"cli.cmd.server.file.update.expectedRevision": "Only update when the server revision still matches.",
 	"cli.cmd.server.file.update.force": "Overwrite the current server content without revision protection.",
 	"cli.cmd.server.file.remove.summary": "Delete a server file.",
-	"cli.cmd.server.file.remove.desc": "Delete an existing server file with revision protection by default.",
+	"cli.cmd.server.file.remove.desc": "Delete an existing server file with revision protection by default.\n\nChoose exactly one of --expected-revision and --force. Confirm the target and revision with info first; --force bypasses revision protection. This deletes the server resource rather than a local copy, so check dependencies and impact first.",
 	"cli.cmd.server.file.remove.expectedRevision": "Only delete when the server revision still matches.",
 	"cli.cmd.server.file.remove.force": "Delete the current server file without revision protection.",
 	"cli.cmd.server.ext.title": "Server extension",
 	"cli.cmd.server.ext.summary": "inspect server extension assets",
-	"cli.cmd.server.ext.desc": "Inspect server extension assets.",
+	"cli.cmd.server.ext.desc": "Inspect server extension assets.\n\nUse template to inspect server-provided extension templates. Create and publish locally through workspace extension.",
 	"cli.cmd.server.ext.template.title": "Server extension template",
 	"cli.cmd.server.ext.template.summary": "inspect server extension templates",
-	"cli.cmd.server.ext.template.desc": "Inspect server extension templates.",
+	"cli.cmd.server.ext.template.desc": "Inspect server extension templates.\n\nlist returns extension points and templates for local extension creation. Templates come from the target server; use the same active server when creating the extension.",
 	"cli.cmd.server.ext.template.list.summary": "List extension templates.",
-	"cli.cmd.server.ext.template.list.desc": "List extension templates available on a server.",
+	"cli.cmd.server.ext.template.list.desc": "List extension templates available on a server.\n\nUse --extension-point to narrow the extension point. Returned extension points and template names are inputs to workspace extension create. Listing does not create or install an extension.",
 	"cli.cmd.server.ext.template.list.extensionPoint": "Only list templates for the given extension point.",
 	"cli.cmd.server.script.title": "Server script",
 	"cli.cmd.server.script.summary": "execute and check server scripts",
-	"cli.cmd.server.script.desc": "Execute and check server scripts.",
+	"cli.cmd.server.script.desc": "Execute and check server scripts.\n\nCheck a local script with check before executing it on the server with exec. A successful check does not imply side-effect-free execution. Scripts may access and modify server resources; inspect the script and target environment first.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Implement business logic\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/app/implement-business-logic.md\nWeb: https://docs.succapp.com/ai-building/app/implement-business-logic#cli-script",
 	"cli.cmd.server.script.done": "Script command completed.",
 	"cli.cmd.server.script.invalidJsonInput": "Invalid JSON input file: {0}",
 	"cli.cmd.server.script.exec.summary": "Execute a local script on the server.",
-	"cli.cmd.server.script.exec.desc": "Read a local script file and execute it through Dev Tool v2 when the server supports this capability.",
+	"cli.cmd.server.script.exec.desc": "Read a local script file and execute it through Dev Tool v2 when the server supports this capability.\n\n<file> selects a local script, --input supplies a JSON input file, and repeatable --param accepts key=value parameters. This executes a real server script; its effects depend on its content. After interruption, inspect actual results before repeating a write.\n\nThe script entry point is function main(args). Read --input JSON from args.input and --param string values from args.params. For example, main(args) can return {mode: args.params.mode, input: args.input}. Validate with check first.",
 	"cli.cmd.server.script.exec.input": "Read script input from a file.",
 	"cli.cmd.server.script.exec.param": "Pass a script parameter. Repeatable.",
 	"cli.cmd.server.script.check.summary": "Check a local script on the server.",
-	"cli.cmd.server.script.check.desc": "Read a local script file and compile it through Dev Tool v2 when the server supports this capability.",
+	"cli.cmd.server.script.check.desc": "Read a local script file and compile it through Dev Tool v2 when the server supports this capability.\n\n<file> selects a local script. The target server must support the compilation endpoint. This does not execute script business logic; a successful check does not validate runtime data, permissions or inputs.",
 	"cli.cmd.server.settings.title": "Server settings",
-	"cli.cmd.server.settings.summary": "get and set server settings",
-	"cli.cmd.server.settings.desc": "Get and set system, project, or app settings through Dev Tool v2.",
+	"cli.cmd.server.settings.summary": "get and edit server settings",
+	"cli.cmd.server.settings.desc": "Read or change settings directly on the remote server; writes do not need workspace push and do not update local files. To review local changes first, clone the project, edit its settings JSON, then use workspace file diff and push. See each subcommand with --help.\n\nUse get to read values, set to modify top-level keys, and add/update/remove for entries in supported settings lists. See child parameters for system, project and app target syntax. Read before writing and verify with get afterwards.\n\nFor a workflow with local review, use workspace file diff and workspace push.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: System settings fields and secret handling\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\nWeb: https://docs.succapp.com/ai-building/basics/system-settings",
 	"cli.cmd.server.settings.target.system": "system",
+	"cli.cmd.server.settings.url": "Remote server URL; alternatively use --server or the active workspace server.",
+	"cli.cmd.server.settings.target": "system for system settings; a project name such as DEMO; or an absolute metadata app path such as /DEMO/app/demo.app, not a local file path.",
+	"cli.cmd.server.settings.itemTarget": "System list alias: llms, sso, credentials, messagers, message-templates, encryption, or masking. For a project name or absolute app metadata path, also provide --key.",
+	"cli.cmd.server.settings.add.item": "One complete item JSON object, including id; do not wrap it in an array.",
+	"cli.cmd.server.settings.update.item": "One complete item JSON object, including id; do not wrap it in an array.",
+	"cli.cmd.server.settings.add.file": "Read one complete item JSON object, including id, from a local file.",
+	"cli.cmd.server.settings.update.file": "Read one complete item JSON object, including id, from a local file.",
+	"cli.cmd.server.settings.add.stdin": "Read one complete item JSON object, including id, from stdin.",
+	"cli.cmd.server.settings.update.stdin": "Read one complete item JSON object, including id, from stdin.",
+	"cli.cmd.server.settings.remove.item": "Item ID, or a JSON object containing only id, such as '{\"id\":\"service-1\"}'.",
+	"cli.cmd.server.settings.remove.file": "Read an item ID or a JSON object containing only id from a local file.",
+	"cli.cmd.server.settings.remove.stdin": "Read an item ID or a JSON object containing only id from stdin.",
 	"cli.cmd.server.settings.get.summary": "Get server settings.",
-	"cli.cmd.server.settings.get.desc": "Read system, project, or app settings. Omit <target> or pass system to read system settings.",
+	"cli.cmd.server.settings.get.desc": "Read remote system, project, or app settings. Omit <target> or pass system for system settings. --key matches a complete top-level key; dots are part of the key, not a nested path.\n\nUse results to inspect current configuration. Secret fields may be sanitized; do not write masked placeholders back unchanged. Before editing a list entry, identify its id and full content.\n\nSystem list keys: llms→llm.services, sso→sso.providers, credentials→service.credentials, messagers→messaging.services, message-templates→messaging.templates, encryption→security.encryption.algorithms, masking→security.masking.rules. For example: get system --key security.masking.rules. Do not use masking as a project target for get.",
 	"cli.cmd.server.settings.get.key": "Only return the given top-level key. Repeatable.",
 	"cli.cmd.server.settings.get.header": "Settings of {0}:",
-	"cli.cmd.server.settings.set.summary": "Set server settings.",
-	"cli.cmd.server.settings.set.desc": "Merge incremental settings into system, project, or app settings. Provide at least one of --set, --file, --stdin or --unset.",
-	"cli.cmd.server.settings.set.set": "Inline incremental JSON. May set multiple top-level keys at once.",
-	"cli.cmd.server.settings.set.file": "Read incremental JSON from a local file.",
-	"cli.cmd.server.settings.set.stdin": "Read incremental JSON from stdin.",
+	"cli.cmd.server.settings.set.summary": "Change remote settings.",
+	"cli.cmd.server.settings.set.desc": "Write directly to the remote server without updating local files; no workspace push is needed. Only submitted top-level keys change. Objects and arrays are replaced in full, not merged recursively; null or --unset removes a key.\n\nChoose one JSON input: --set, --file, or --stdin; --unset may be used alone or with an input. Use complete settings keys (for example system.name), not nested JSON. Read the current value before changing an object or array, and use get again to verify the saved value.\n\nUse --expected-revision for concurrency protection. After a conflict, reread and reconcile the required top-level changes before submitting. After interruption, inspect with get rather than assuming nothing was saved.\n\nget does not return a settings revision from the same snapshot for concurrency protection. Do not substitute a file revision or another version number. Entry add/update/remove also expose no caller-supplied revision parameter.",
+	"cli.cmd.server.settings.set.set": "Inline JSON object with complete values for the keys to change.",
+	"cli.cmd.server.settings.set.file": "Read a JSON object from a local file and submit it to the remote server; does not edit or sync that file.",
+	"cli.cmd.server.settings.set.stdin": "Read settings JSON from stdin.",
 	"cli.cmd.server.settings.set.unset": "Delete the given top-level key. Repeatable.",
-	"cli.cmd.server.settings.set.key": "Only merge under the given top-level key.",
+	"cli.cmd.server.settings.set.key": "Treat the input object as this key's complete value, instead of a settings patch. Cannot combine with --unset.",
 	"cli.cmd.server.settings.set.expectedRevision": "Only set when the server settings revision still matches.",
 	"cli.cmd.server.settings.set.success": "Updated settings of {0}: {1}",
 	"cli.cmd.server.settings.set.noKeys": "(no keys)",
+	"cli.cmd.server.settings.add.summary": "Add a settings item.",
+	"cli.cmd.server.settings.add.key": "Complete top-level key of the item list; required unless <target> is a system list alias.",
+	"cli.cmd.server.settings.add.desc": "Add one complete item directly to a remote settings list. Provide exactly one of --item, --file, or --stdin. The JSON object must include a new id and all required fields for its type; no workspace push is needed.\n\nRead the list and existing IDs with get first to avoid duplicates. Read again after submission. After an interrupted response, check whether the entry was added before retrying.\n\nConsult the corresponding system settings documentation using the list keys described by get. Existing entries of the same type can illustrate structure, but a new entry must have a new id.\n\nGuide: System settings fields and secret handling\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\nWeb: https://docs.succapp.com/ai-building/basics/system-settings",
+	"cli.cmd.server.settings.add.success": "Added item {1} to {0}.",
+	"cli.cmd.server.settings.update.summary": "Update a settings item.",
+	"cli.cmd.server.settings.update.key": "Complete top-level key of the item list; required unless <target> is a system list alias.",
+	"cli.cmd.server.settings.update.desc": "Replace one item directly in a remote settings list; no workspace push is needed. Read the list first, for example with server settings get system --key security.masking.rules, then supply one complete item with its existing id using --item, --file, or --stdin. Omitted item fields are not preserved.\n\nPreserve every field still needed in the complete entry, especially objects and arrays. Reread after saving. If the response is interrupted, inspect the current entry before retrying.\n\nGuide: System settings fields and secret handling\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\nWeb: https://docs.succapp.com/ai-building/basics/system-settings",
+	"cli.cmd.server.settings.update.success": "Updated item {1} in {0}.",
+	"cli.cmd.server.settings.remove.summary": "Remove a settings item.",
+	"cli.cmd.server.settings.remove.key": "Complete top-level key of the item list; required unless <target> is a system list alias.",
+	"cli.cmd.server.settings.remove.desc": "Remove one item directly from a remote settings list; no workspace push is needed. Provide exactly one of --item, --file, or --stdin, containing the item id or a JSON object with only id.\n\nInspect the entry ID and purpose with get first; removal directly affects server configuration. Reread afterwards to verify. Use set --unset to delete an entire top-level settings key.",
+	"cli.cmd.server.settings.remove.success": "Removed item {1} from {0}.",
+	"cli.cmd.server.settings.*.module": "System settings list module.",
+	"cli.cmd.server.settings.*.item": "Inline complete item JSON, or an ID for remove.",
+	"cli.cmd.server.settings.*.file": "Read item JSON or ID from a local file.",
+	"cli.cmd.server.settings.*.stdin": "Read item JSON or ID from stdin.",
+	"cli.cmd.server.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.file.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.file.*.path": "Server metadata path such as /DEMO/ana/sales.dash, not a local filesystem path.",
+	"cli.cmd.server.file.*.id": "Metadata ID obtainable from file information returned by server file info.",
+	"cli.cmd.server.cache.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.cache.clean.name": "Cache name returned by server cache list; choose this or --all.",
+	"cli.cmd.server.cluster.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.cluster.*.nodeId": "Node ID returned by server cluster list.",
+	"cli.cmd.server.thread.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.thread.*.threadId": "Thread ID from server thread list on the same node; recheck before use.",
+	"cli.cmd.server.techLog.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.proj.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.script.*.file": "Local script file; relative paths use the CLI launch directory, unaffected by -C.",
+	"cli.cmd.server.techLog.level.*.url": "Target server URL; takes precedence over --server, the active workspace server and SUCCAPP_SERVER.",
+	"cli.cmd.server.proj.create.project": "New project name; inspect existing projects with server project list.",
 	"cli.cmd.workspace.title": "Workspace",
 	"cli.cmd.workspace.summary": "work with a local SuccApp workspace",
-	"cli.cmd.workspace.desc": "Work with a local SuccApp workspace.",
+	"cli.cmd.workspace.desc": "Work with a local SuccApp workspace.\n\nRun inside an initialized workspace or select one with -C. Confirm the active server with remote, then obtain projects with project clone. After editing, use status, file diff and push to inspect and submit changes.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Initialize a workspace\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/init-workspace.md\nWeb: https://docs.succapp.com/ai-building/workspace/init-workspace",
 	"cli.cmd.workspace.init.summary": "Initialize a SuccApp workspace.",
-	"cli.cmd.workspace.init.desc": "Initialize .succapp/config.json, recommended workspace support files, and the optional offline SuccApp docs skill.",
+	"cli.cmd.workspace.init.desc": "Initialize .succapp/config.json, recommended workspace support files, and the optional offline SuccApp docs skill.\n\nThe target directory must already exist. Use --scope to choose initialization tasks. Re-running respects existing configuration and is not a clean reset. Server access and offline-document downloads may need network access and authentication; inspect updated, skipped and document status in the result.\n\nscope defaults to all: base maintains workspace configuration, editor settings, ignore rules and Agent files; dev maintains local types and JSON Schema; agent-docs installs or updates the official documentation skill.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Initialize a workspace\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/init-workspace.md\nWeb: https://docs.succapp.com/ai-building/workspace/init-workspace",
 	"cli.cmd.workspace.init.server": "Initialize the workspace with this active server.",
 	"cli.cmd.workspace.init.scope": "Limit initialization scope. Values: base, dev, agent-docs, all.",
 	"cli.cmd.workspace.init.force": "Force the offline SuccApp docs skill to check local files even when the index is unchanged.",
@@ -770,25 +825,25 @@
 	"cli.cmd.workspace.init.supportFiles": "Workspace support files: {0} updated, {1} skipped.",
 	"cli.cmd.workspace.init.workspaceInit": "Workspace already initialized: {0}",
 	"cli.cmd.workspace.status.summary": "Show workspace sync status.",
-	"cli.cmd.workspace.status.desc": "Show workspace sync status.",
+	"cli.cmd.workspace.status.desc": "Show workspace sync status.\n\nInspect local and remote changes by default. --local-only checks local state; --force-refresh recalibrates remote caches. Check the exit code, remoteCheck and warnings before interpreting changes. remoteCheck=complete means this remote check completed; skipped means it was intentionally omitted. failed/cancelled means incomplete checking and a nonzero exit code. A failed check may retain previous remote changes; empty results do not prove the remote is unchanged.\n\nFor authentication failures, run auth login. For connection failures, verify the target and network, then rerun workspace status --force-refresh. Do not treat incomplete results as a complete pre-push check.",
 	"cli.cmd.workspace.status.forceRefresh": "Recheck server changes instead of using cached status.",
 	"cli.cmd.workspace.status.localOnly": "Show only local workspace changes; do not check the server.",
 	"cli.cmd.workspace.status.remoteAuthRequired": "You are not logged in, so only local changes are shown. Run 'succapp auth login', then retry to include server changes.",
 	"cli.cmd.workspace.upgrade.summary": "Plan workspace structure migrations.",
-	"cli.cmd.workspace.upgrade.desc": "Plan SuccApp workspace structure migrations. The current implementation has no migrations.",
+	"cli.cmd.workspace.upgrade.desc": "Plan SuccApp workspace structure migrations. The current implementation has no migrations.\n\nThis concerns workspace structure, not metadata file versions. Use workspace file upgrade for old metadata files and succapp --version for the CLI version.",
 	"cli.cmd.workspace.upgrade.targetVersion": "Plan migration to the target workspace structure version.",
 	"cli.cmd.workspace.upgrade.dryRun": "Preview the migration plan without changing files.",
 	"cli.cmd.workspace.upgrade.actions": "Workspace upgrade: {0} action(s). current={1}, target={2}.",
 	"cli.cmd.workspace.upgrade.noActions": "Workspace upgrade: no actions. current={0}, target={1}.",
 	"cli.cmd.workspace.pull.summary": "Pull server changes into the workspace.",
-	"cli.cmd.workspace.pull.desc": "Apply changes from the active server into the current workspace.",
+	"cli.cmd.workspace.pull.desc": "Apply changes from the active server into the current workspace.\n\nUse paths to narrow the scope; omitted paths use the current synchronization scope. Pull changes local files and may merge changes. Inspect status and file diff first; examine reported conflicts before resolving them, rather than treating --force as an ordinary retry.\n\nOmitting paths processes all corresponding changes. A kind=result response still exits with 6 when conflicts exist. Inspect updated, deleted, conflicts and oldFiles, and use backup list to inspect saved local versions.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Synchronize changes\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\nWeb: https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.pull.force": "Allow server changes to overwrite local changes.",
 	"cli.cmd.workspace.pull.conflicts": "Conflicts: {0}",
 	"cli.cmd.workspace.pull.oldMeta": "Old metadata files: {0}",
 	"cli.cmd.workspace.pull.pullResultUpdated": "Pull result: {0} updated, {1} deleted, {2} conflict(s)",
 	"cli.cmd.workspace.pull.upDate": "Already up to date",
 	"cli.cmd.workspace.push.summary": "Push workspace changes to the server.",
-	"cli.cmd.workspace.push.desc": "Submit local workspace changes to the active server.",
+	"cli.cmd.workspace.push.desc": "Submit local workspace changes to the active server.\n\nUse paths to narrow the scope. Inspect status and file diff to confirm local changes and the active server. Push writes remote metadata; --force bypasses some conflict protection. After failure or disconnection, refresh state before retrying.\n\nOmitting paths processes all corresponding local changes. Recheck status afterwards; a result object does not override failed items or a nonzero exit code.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Synchronize changes\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\nWeb: https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.push.force": "Allow local changes to overwrite remote changes.",
 	"cli.cmd.workspace.push.failed": "Failed files: {0}",
 	"cli.cmd.workspace.push.kind": "Kind",
@@ -800,14 +855,14 @@
 	"cli.cmd.workspace.push.targetVersion": "Target version",
 	"cli.cmd.workspace.push.version": "Current version",
 	"cli.cmd.workspace.discard.summary": "Discard local workspace changes.",
-	"cli.cmd.workspace.discard.desc": "Restore workspace files from the local mirror baseline and discard local changes.",
+	"cli.cmd.workspace.discard.desc": "Restore workspace files from the local mirror baseline and discard local changes.\n\nExplicit paths discard local changes in that scope. Without paths, --force is required to confirm the full scope. The mirror is a local synchronization baseline and may not be the latest server version. Review differences and save any work you need first.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Synchronize changes\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\nWeb: https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.discard.force": "Confirm discarding all workspace changes when no path is given.",
 	"cli.cmd.workspace.discard.deletedFiles": "Deleted files: {0}",
 	"cli.cmd.workspace.discard.noLocalChanges": "No local changes to discard",
 	"cli.cmd.workspace.discard.restoredFiles": "Restored files: {0}",
 	"cli.cmd.workspace.discard.result": "Discard result: {0} restored, {1} deleted",
 	"cli.cmd.workspace.repair.summary": "Check or repair workspace consistency issues.",
-	"cli.cmd.workspace.repair.desc": "Check or repair workspace structure and sync state issues that can be fixed automatically.",
+	"cli.cmd.workspace.repair.desc": "Check or repair workspace structure and sync state issues that can be fixed automatically.\n\nStart with --dry-run to inspect findings and use --only to narrow checks before repairing. Repair may update support files or synchronization state. It does not replace business-file conflict resolution; inspect status afterwards.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Validate metadata\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/troubleshoot/metadata-validation.md\nWeb: https://docs.succapp.com/ai-building/troubleshoot/metadata-validation",
 	"cli.cmd.workspace.repair.only": "Run only the named workspace repair check.",
 	"cli.cmd.workspace.repair.dryRun": "Preview repairable workspace issues without changing files.",
 	"cli.cmd.workspace.repair.badCheck": "Invalid workspace repair check: {0}",
@@ -824,43 +879,43 @@
 	"cli.cmd.workspace.repair.unresolved": "Unresolved issues:",
 	"cli.cmd.workspace.proj.title": "Workspace project",
 	"cli.cmd.workspace.proj.summary": "manage workspace projects",
-	"cli.cmd.workspace.proj.desc": "Manage workspace projects.",
+	"cli.cmd.workspace.proj.desc": "Manage workspace projects.\n\nUse list for local projects, clone to download from the active server, and remove to delete local projects and baselines. Use succapp server project list to discover server projects.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Connect and clone projects\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\nWeb: https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.proj.list.summary": "List workspace projects.",
-	"cli.cmd.workspace.proj.list.desc": "List workspace projects.",
+	"cli.cmd.workspace.proj.list.desc": "List workspace projects.\n\nShows projects found in both the working directory and mirror baseline, helping identify a missing side. This is not the server project list; use server project list for that.",
 	"cli.cmd.workspace.proj.list.empty": "No projects are tracked in this workspace.",
 	"cli.cmd.workspace.proj.clone.summary": "Clone server projects into the workspace.",
-	"cli.cmd.workspace.proj.clone.desc": "Clone projects from the active server into the current workspace.",
+	"cli.cmd.workspace.proj.clone.desc": "Clone projects from the active server into the current workspace.\n\nConfirm the active server and project names first. Existing local projects or baselines require --force to confirm replacement. Clone writes the working directory and baseline; preserve local changes first. Check any old-metadata notices afterwards.\n\nOmitting project names clones all visible projects. If no active server is configured, --server can select and register the initial target. Once an active server exists, --server must match it.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Connect and clone projects\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\nWeb: https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.proj.clone.force": "Allow clone to overwrite existing local workspace projects.",
 	"cli.cmd.workspace.proj.clone.configuredActive": "Active server configured: {0}",
 	"cli.cmd.workspace.proj.clone.cloned": "Cloned projects: {0}",
 	"cli.cmd.workspace.proj.clone.oldMetaNotice": "Note: {count} metadata file(s) use an older format.\nOptional: run '{command}' to modernize them.\nThis may update many files; run with `--dry-run` first to review the scope.\nSkip this if you only want to inspect the project.",
 	"cli.cmd.workspace.proj.remove.summary": "Remove workspace projects.",
-	"cli.cmd.workspace.proj.remove.desc": "Remove local workspace projects and mirror baselines without deleting server projects.",
+	"cli.cmd.workspace.proj.remove.desc": "Remove local workspace projects and mirror baselines without deleting server projects.\n\n--force is required, and multiple projects can be specified. Unpushed local changes and the project synchronization baseline are removed. Save anything you need first; projects can later be cloned again from the server.",
 	"cli.cmd.workspace.proj.remove.force": "Confirm removal of local project files and mirror baselines.",
 	"cli.cmd.workspace.proj.remove.removed": "Removed workspace projects: {0}",
 	"cli.cmd.workspace.remote.title": "Workspace remote",
 	"cli.cmd.workspace.remote.summary": "manage workspace remotes",
-	"cli.cmd.workspace.remote.desc": "Manage workspace remotes.",
+	"cli.cmd.workspace.remote.desc": "Manage workspace remotes.\n\nThese commands manage local workspace configuration; use auth for credentials. Confirm server identity before switching or changing a URL, since subsequent synchronization uses the active server.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Connect and clone projects\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\nWeb: https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.remote.list.summary": "List configured servers.",
-	"cli.cmd.workspace.remote.list.desc": "List configured servers for the current workspace.",
+	"cli.cmd.workspace.remote.list.desc": "List configured servers for the current workspace.\n\nCheck the active marker to confirm the target for subsequent synchronization. Entries come from local configuration and do not prove reachability or valid authentication.",
 	"cli.cmd.workspace.remote.add.summary": "Add a server and make it active.",
-	"cli.cmd.workspace.remote.add.desc": "Add a server to the current SuccApp workspace and make it the active server.",
+	"cli.cmd.workspace.remote.add.desc": "Add a server to the current SuccApp workspace and make it the active server.\n\n<url> is the server address. Adding it changes the current synchronization target. Configure credentials with auth login; adding a server does not clone projects.",
 	"cli.cmd.workspace.remote.add.active": "Active server: {0}",
 	"cli.cmd.workspace.remote.use.summary": "Switch the active server.",
-	"cli.cmd.workspace.remote.use.desc": "Switch the active server for the current workspace.",
+	"cli.cmd.workspace.remote.use.desc": "Switch the active server for the current workspace.\n\n<url> must identify a configured server. Check remote list and status afterwards. Switching does not automatically replace the working directory with files from the new server.",
 	"cli.cmd.workspace.remote.use.active": "Active server: {0}",
 	"cli.cmd.workspace.remote.setUrl.summary": "Change a configured server URL.",
-	"cli.cmd.workspace.remote.setUrl.desc": "Change a configured server URL and migrate the local mirror key.",
+	"cli.cmd.workspace.remote.setUrl.desc": "Change a configured server URL and migrate the local mirror key.\n\nProvide old and new URLs when the same server changes address. This changes local configuration and baseline indexing; it is not a project migration to an unrelated server. Check remote list and authentication afterwards.",
 	"cli.cmd.workspace.remote.setUrl.changed": "Server URL changed: {0} -> {1}",
 	"cli.cmd.workspace.remote.remove.summary": "Remove a configured server.",
-	"cli.cmd.workspace.remote.remove.desc": "Remove a server from the current workspace configuration.",
+	"cli.cmd.workspace.remote.remove.desc": "Remove a server from the current workspace configuration.\n\n<url> must be configured. Check remote list afterwards to confirm the remaining active target. This does not delete the remote server or its projects; use auth logout to remove local credentials.",
 	"cli.cmd.workspace.remote.remove.active": "Server removed: {0}\nActive server: {1}",
 	"cli.cmd.workspace.remote.remove.removed": "Server removed: {0}",
 	"cli.cmd.workspace.file.title": "Workspace file",
 	"cli.cmd.workspace.file.summary": "inspect workspace files",
-	"cli.cmd.workspace.file.desc": "Inspect workspace files.",
+	"cli.cmd.workspace.file.desc": "Inspect workspace files.\n\nUse resolve for path mapping, show/history for server or baseline content, diff to compare local and server content, compile/upgrade to validate or upgrade local metadata, and open for server pages. Local file edits still require push to synchronize.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Synchronize changes\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\nWeb: https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.file.resolve.summary": "Resolve a workspace file path.",
-	"cli.cmd.workspace.file.resolve.desc": "Resolve local, remote, and browser URLs for a workspace file.",
+	"cli.cmd.workspace.file.resolve.desc": "Resolve local, remote, and browser URLs for a workspace file.\n\nPass a workspace file path and inspect the resolved localPath and remotePath. --url selects a view or edit link. This resolves the target without uploading files or opening a browser.",
 	"cli.cmd.workspace.file.resolve.url": "Only print the view or edit URL in human mode.",
 	"cli.cmd.workspace.file.resolve.badUrl": "Invalid value for --url: {0}",
 	"cli.cmd.workspace.file.resolve.editUrl": "Edit URL: {0}",
@@ -869,7 +924,7 @@
 	"cli.cmd.workspace.file.resolve.remote": "Remote path: {0}",
 	"cli.cmd.workspace.file.resolve.viewUrl": "View URL: {0}",
 	"cli.cmd.workspace.file.open.summary": "Open the server file page.",
-	"cli.cmd.workspace.file.open.desc": "Open the server view or edit page for a workspace file, or return its URL without opening the browser.",
+	"cli.cmd.workspace.file.open.desc": "Open the server view or edit page for a workspace file, or return its URL without opening the browser.\n\nThe default opens a view page; --edit selects editing and --no-open returns only the URL. Pages use server content. Local changes require --force confirmation, which does not push those changes.",
 	"cli.cmd.workspace.file.open.edit": "Open the server edit page instead of the view page.",
 	"cli.cmd.workspace.file.open.noOpen": "Return the page URL without launching the system browser.",
 	"cli.cmd.workspace.file.open.path": "Workspace-relative file path or absolute server metadata path.",
@@ -878,21 +933,21 @@
 	"cli.cmd.workspace.file.open.openedEdit": "Opened server edit page: {0}",
 	"cli.cmd.workspace.file.open.openedView": "Opened server view page: {0}",
 	"cli.cmd.workspace.file.show.summary": "Show file content.",
-	"cli.cmd.workspace.file.show.desc": "Show file content.",
+	"cli.cmd.workspace.file.show.desc": "Read file content from the server or local mirror baseline.\n\nReads server content by default; --source=mirror reads the local baseline. --revision applies only to the server source. Human output is raw content and JSON content is Base64. This does not directly read the current working file.",
 	"cli.cmd.workspace.file.show.source": "Read from mirror or server.",
 	"cli.cmd.workspace.file.show.revision": "Read a server revision.",
 	"cli.cmd.workspace.file.show.badRev": "Invalid value for --revision: {0}",
 	"cli.cmd.workspace.file.show.badSource": "Invalid value for --source: {0}",
 	"cli.cmd.workspace.file.show.revSource": "--revision is only supported with --source=server.",
 	"cli.cmd.workspace.file.diff.summary": "Show workspace diff against server.",
-	"cli.cmd.workspace.file.diff.desc": "Compare local workspace metadata files with server content. Inputs may be files, directories (recursively including all files), or globs.",
+	"cli.cmd.workspace.file.diff.desc": "Compare local workspace metadata files with server content. Inputs may be files, directories (recursively including all files), or globs.\n\nQuote globs so the CLI can expand them. Output is for reviewing differences and does not change local or server files. Combine it with workspace status to inspect conflicts across the synchronization scope.",
 	"cli.cmd.workspace.file.diff.source": "Compare against server content.",
 	"cli.cmd.workspace.file.diff.badSource": "Invalid value for --source: {0}",
 	"cli.cmd.workspace.file.history.summary": "Show server file history.",
-	"cli.cmd.workspace.file.history.desc": "Show server-side file history for a workspace file.",
+	"cli.cmd.workspace.file.history.desc": "Show server-side file history for a workspace file.\n\nResolves a workspace path to a file on the active server; --limit bounds the number of entries. This is server history, not local Git history. Read a version with file show --revision.",
 	"cli.cmd.workspace.file.history.limit": "Limit the number of history records.",
 	"cli.cmd.workspace.file.compile.summary": "Validate workspace metadata files.",
-	"cli.cmd.workspace.file.compile.desc": "Validate local workspace metadata files. Inputs may be files, directories (recursively including all files), or globs.",
+	"cli.cmd.workspace.file.compile.desc": "Validate local workspace metadata files. Inputs may be files, directories (recursively including all files), or globs.\n\nQuote globs. Validation may contact the server for version information or compilation checks, but does not push local changes. Inspect failed and skipped items; successful validation does not verify business behavior.\n\nExit 0 may still include skipped items. Inspect skipped/skipReason rather than treating skipped files as validated.",
 	"cli.cmd.workspace.file.compile.compiler": "Compiler",
 	"cli.cmd.workspace.file.compile.done": "Validated {0} workspace metadata file(s).",
 	"cli.cmd.workspace.file.compile.failed": "Failed files: {0}",
@@ -904,7 +959,7 @@
 	"cli.cmd.workspace.file.compile.skipped": "Skipped files: {0}",
 	"cli.cmd.workspace.file.compile.upgradeRequired": "{0} file(s) require a metadata upgrade. Run `{1}` with the same pathspec, then validate again.",
 	"cli.cmd.workspace.file.upgrade.summary": "Upgrade old SuccApp metadata files.",
-	"cli.cmd.workspace.file.upgrade.desc": "Preview or upgrade old SuccApp metadata files in the local workspace. Inputs may be files, directories (recursively including all files), or globs; with no input, all local projects are processed.",
+	"cli.cmd.workspace.file.upgrade.desc": "Preview or upgrade old SuccApp metadata files in the local workspace. Inputs may be files, directories (recursively including all files), or globs; with no input, all local projects are processed.\n\nUse --dry-run to inspect candidates and failures before upgrading. Actual execution changes local files. Review diff and validate afterwards before deciding to push.",
 	"cli.cmd.workspace.file.upgrade.dryRun": "Preview upgrade candidates without changing files.",
 	"cli.cmd.workspace.file.upgrade.cands": "Upgrade candidates: {0}",
 	"cli.cmd.workspace.file.upgrade.dryRunRes": "Metadata upgrade dry-run: {0} checked, {1} candidate(s), {2} skipped, {3} failed",
@@ -915,52 +970,67 @@
 	"cli.cmd.workspace.file.upgrade.upgraded": "Upgraded files: {0}",
 	"cli.cmd.workspace.lock.title": "Workspace lock",
 	"cli.cmd.workspace.lock.summary": "inspect workspace locks",
-	"cli.cmd.workspace.lock.desc": "Inspect workspace locks.",
+	"cli.cmd.workspace.lock.desc": "Inspect workspace locks.\n\nlist shows occupied scopes, status inspects selected scopes, and wait waits for release. These commands diagnose concurrent work; they do not forcibly remove locks or terminate holders.",
 	"cli.cmd.workspace.lock.badScope": "Invalid workspace lock scope: {0}",
 	"cli.cmd.workspace.lock.list.summary": "List locked workspace scopes.",
-	"cli.cmd.workspace.lock.list.desc": "List scopes currently locked in the SuccApp workspace.",
+	"cli.cmd.workspace.lock.list.desc": "List scopes currently locked in the SuccApp workspace.\n\nUse output to identify holders and scopes. An empty list means no valid holders were observed. Other processes may change this state; it does not reserve a lock for the next write.",
 	"cli.cmd.workspace.lock.list.scope": "Scope",
 	"cli.cmd.workspace.lock.list.empty": "No active workspace locks.",
 	"cli.cmd.workspace.lock.status.summary": "Show workspace lock holders.",
-	"cli.cmd.workspace.lock.status.desc": "Workspace lock status",
+	"cli.cmd.workspace.lock.status.desc": "Inspect workspace lock scopes and their holders.\n\nSpecify one or more scopes, or omit them to inspect all scopes. free/busy reflects the instant inspected. Use lock wait to wait for availability; subsequent operations must still acquire their own locks.",
 	"cli.cmd.workspace.lock.status.heartbeat": "Last heartbeat",
 	"cli.cmd.workspace.lock.status.pid": "PID",
 	"cli.cmd.workspace.lock.status.scope": "Scope",
 	"cli.cmd.workspace.lock.wait.summary": "Wait until workspace locks are free.",
-	"cli.cmd.workspace.lock.wait.desc": "Wait until the requested workspace lock scopes are free.",
+	"cli.cmd.workspace.lock.wait.desc": "Wait until the requested workspace lock scopes are free.\n\nWith no scopes, waits for config and sync. --timeout is in seconds; omitting it waits indefinitely. Success means the scopes were free when inspected and does not acquire them. Timeout returns a nonzero exit code that scripts should handle.\n\nThe timeout exit code is 124.",
 	"cli.cmd.workspace.lock.wait.timeout": "Stop waiting after the given number of seconds.",
 	"cli.cmd.workspace.lock.wait.badTimeout": "Invalid value for --timeout: {0}",
 	"cli.cmd.workspace.lock.wait.locksBusy": "Workspace locks still busy after {0}s: {1}",
 	"cli.cmd.workspace.lock.wait.locksFree": "Workspace locks are free: {0}",
 	"cli.cmd.workspace.backup.title": "Workspace backup",
 	"cli.cmd.workspace.backup.summary": "inspect and clear workspace backups",
-	"cli.cmd.workspace.backup.desc": "Inspect and clear workspace backups.",
+	"cli.cmd.workspace.backup.desc": "Inspect and clear workspace backups.\n\nUse list to inspect local versions saved before pull conflict handling and clear to remove them. These are not complete backups of every workspace file and do not replace Git history.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Recover lost changes\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/troubleshoot/recover-lost-changes.md\nWeb: https://docs.succapp.com/ai-building/troubleshoot/recover-lost-changes",
 	"cli.cmd.workspace.backup.backupPath": "Backup path",
 	"cli.cmd.workspace.backup.cleared": "Merge backup clear: {0} cleared, {1} remaining.",
 	"cli.cmd.workspace.backup.list.summary": "List saved merge backups.",
-	"cli.cmd.workspace.backup.list.desc": "List local versions saved before pull conflict handling.",
+	"cli.cmd.workspace.backup.list.desc": "List local versions saved before pull conflict handling.\n\nUse paths to limit the scope. Identify the original file and saved location before restoring or cleaning backups. Listing does not restore files automatically.",
 	"cli.cmd.workspace.backup.list.empty": "No merge backups found.",
 	"cli.cmd.workspace.backup.clear.summary": "Clear saved merge backups.",
-	"cli.cmd.workspace.backup.clear.desc": "Clear local versions saved before pull conflict handling.",
+	"cli.cmd.workspace.backup.clear.desc": "Clear local versions saved before pull conflict handling.\n\nUse paths to limit the scope. Omitting paths clears all such backups without an additional --force. Inspect list and preserve anything needed for recovery first. Cleanup does not modify current working files or remote files.",
 	"cli.cmd.workspace.ext.title": "Workspace extension",
 	"cli.cmd.workspace.ext.summary": "create and publish workspace extensions",
-	"cli.cmd.workspace.ext.desc": "Create and publish workspace extensions.",
+	"cli.cmd.workspace.ext.desc": "Create and publish workspace extensions.\n\nUse list for local extensions, create to generate a local directory from a template, and push to publish to the active server. Discover templates with server extension template list first.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nGuide: Develop extensions\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/extension/extension.md\nWeb: https://docs.succapp.com/ai-building/extension/extension",
 	"cli.cmd.workspace.ext.dirNamedSame": "A directory named the same already exists under sysdata/extensions/.",
 	"cli.cmd.workspace.ext.extNameMust": "Extension name must follow the pattern {0}.",
 	"cli.cmd.workspace.ext.extNameRequired": "Extension name is required.",
 	"cli.cmd.workspace.ext.invalidExtName": "Invalid extension name.",
 	"cli.cmd.workspace.ext.middleSegmentMust": "The middle segment must equal \"{0}\" (current: \"{1}\").",
 	"cli.cmd.workspace.ext.list.summary": "List local extensions.",
-	"cli.cmd.workspace.ext.list.desc": "List local extensions under the workspace sysdata project.",
+	"cli.cmd.workspace.ext.list.desc": "List local extensions under the workspace sysdata project.\n\nLists extension directories under sysdata in the current workspace, not extensions installed on the server. Use a confirmed name with extension push.",
 	"cli.cmd.workspace.ext.create.summary": "Create a local extension.",
-	"cli.cmd.workspace.ext.create.desc": "Create a local extension directory from a server template.",
+	"cli.cmd.workspace.ext.create.desc": "Create a local extension directory from a server template.\n\nRequires an extension point, template and new name. Discover valid combinations with server extension template list. This writes a local directory; inspect generated files before publishing with extension push.\n\nAn active server and a cloned sysdata project are required. Templates are fetched over the network; JSON execution.server=none does not mean this operation can run offline.\n\nConsult the guide below for related instructions and confirm it applies to your CLI and server version.\n\nNames use lowercase letters, digits and hyphens, with at least three segments. The second segment must match the extension point, e.g. succ-component-card. The destination directory must not already exist.\n\nGuide: Develop extensions\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/extension/extension.md\nWeb: https://docs.succapp.com/ai-building/extension/extension",
 	"cli.cmd.workspace.ext.create.extTemplate": "Extension template not found: {0}/{1}",
 	"cli.cmd.workspace.ext.push.summary": "Push a local extension.",
-	"cli.cmd.workspace.ext.push.desc": "Push a local extension directory to the active server.",
+	"cli.cmd.workspace.ext.push.desc": "Push a local extension directory to the active server.\n\nChoose exactly one of an extension name and --path. This uploads the extension and affects the server. Confirm its content and the active server first; see --force when replacing an existing target.",
 	"cli.cmd.workspace.ext.push.path": "Resolve the extension from a local path under sysdata/extensions.",
 	"cli.cmd.workspace.ext.push.force": "Allow local extension files to overwrite remote changes.",
 	"cli.cmd.workspace.ext.push.needNamePath": "Pass an extension name or --path=<path>.",
 	"cli.cmd.workspace.ext.push.onlyOne": "Use either <name> or --path=<path>, not both.",
+	"cli.cmd.workspace.*.path": "Workspace resource path: a local path or /PROJECT/... metadata path. See the description for omitted-path scope.",
+	"cli.cmd.workspace.file.*.pathspec": "Relative paths and globs are expanded from the workspace root, not the launch subdirectory. Directories are recursive; quote globs. Workspace-local absolute paths and /PROJECT/... metadata paths are supported.",
+	"cli.cmd.workspace.file.*.path": "Workspace resource path: a local path or /PROJECT/... metadata path. See the description for omitted-path scope.",
+	"cli.cmd.workspace.remote.*.url": "Configured or new server URL, such as https://bi.example.com.",
+	"cli.cmd.workspace.remote.*.oldUrl": "Configured old server URL.",
+	"cli.cmd.workspace.remote.*.newUrl": "New access URL for the same server.",
+	"cli.cmd.workspace.lock.*.scope": "Workspace lock scopes such as config and sync; see the description for defaults.",
+	"cli.cmd.workspace.backup.*.path": "Workspace resource path: a local path or /PROJECT/... metadata path. See the description for omitted-path scope.",
+	"cli.cmd.workspace.ext.*.extensionPoint": "Extension point returned by server extension template list.",
+	"cli.cmd.workspace.ext.*.template": "Template name within the selected extension point, from server extension template list.",
+	"cli.cmd.workspace.ext.create.name": "New extension name following the selected extension point naming requirements.",
+	"cli.cmd.workspace.ext.push.name": "Extension name returned by workspace extension list; choose this or --path.",
+	"cli.cmd.workspace.proj.clone.project": "Project names from server project list (remote) or workspace project list (local).",
+	"cli.cmd.workspace.proj.remove.project": "Project names from server project list (remote) or workspace project list (local).",
+	"cli.cmd.workspace.status.incomplete": "Remote check incomplete ({0}); remote changes may be from a previous check. Inspect warnings and check again.",
 	"cli.out.search.score": "Score",
 	"cli.out.common.active": "Active",
 	"cli.out.common.api": "Dev Tool API",
@@ -1081,9 +1151,9 @@
 	"cli.out.header.upgrade": "Upgradeable",
 	"cli.out.header.value": "Value",
 	"cli.out.header.version": "Version",
-	"cli.out.help.commandHelpRead": "Run 'succapp {0} <command> --help' to read about a specific command.",
+	"cli.out.help.commandHelpRead": "Run 'succapp {0} <command> --help' to see the next level.",
 	"cli.out.help.commandHelpSee": "Run 'succapp <command> --help' to see command help.",
-	"cli.out.help.commands": "Commands",
+	"cli.out.help.commands": "Commands:",
 	"cli.out.help.arguments": "arguments:",
 	"cli.out.help.examples": "examples:",
 	"cli.out.help.group.content": "content options:",
@@ -1094,7 +1164,7 @@
 	"cli.out.help.group.output": "output options:",
 	"cli.out.help.group.query": "query options:",
 	"cli.out.help.group.search": "search options:",
-	"cli.out.help.usageHeader": "usage:",
+	"cli.out.help.usageHeader": "usage: ",
 	"cli.out.help.usageLine": "usage: succapp {command} {usageArgs}",
 	"cli.out.human.error": "error: {0}",
 	"cli.out.human.hint": "hint: {0}",
@@ -1140,6 +1210,8 @@
 	"cli.out.workspace.ext.version": "Current version",
 	"cli.out.workspace.file.hist.empty": "No server history records",
 	"cli.out.workspace.file.history.badLimit": "Invalid value for --limit: {0}",
+	"cli.out.help.commandGroups": "Command groups:",
+	"cli.out.help.rootUsage": "succapp [global options] <command> [<args>]",
 	"cli.err.context.exampleCommandServer": "succapp --server=<url> {commandName}",
 	"cli.err.context.exampleCommandUrl": "succapp {commandName} <url>",
 	"cli.err.context.exampleEnvUrl": "{envName}=<url> succapp {commandName}",
@@ -1326,6 +1398,7 @@
 	"vs.cmd.sync.upgradeMeta.result": "Metadata upgrade finished: {0} changed, {1} checked.",
 	"vs.cmd.sync.upgradeMeta.upgrade": "Upgrade",
 	"vs.cmd.sync.upgradeMeta.upgradeMetaFile": "Upgrade {0} metadata file(s) under this folder?",
+	"vs.cmd.sync.push.upgradeRequired": "Upgrade {0} old metadata file(s) before pushing? Cancelling will stop this push.",
 	"vs.cmd.ext.create.cannotCreateExt": "Cannot create an extension because the sysdata project is not cloned in this workspace.",
 	"vs.cmd.ext.create.createdExt": "Created extension {0}.",
 	"vs.cmd.ext.create.dirNamedSame": "A directory named the same already exists under sysdata/extensions/.",
@@ -1440,9 +1513,9 @@
 	"vs.ui.workspaceProblem.syncProblem": "SuccApp detected a workspace sync problem. See logs for details.",
 	"cli.cmd.model.title": "Model",
 	"cli.cmd.model.summary": "inspect and query semantic data models",
-	"cli.cmd.model.desc": "Inspect and query SuccApp semantic data models.",
+	"cli.cmd.model.desc": "Inspect and query SuccApp semantic data models.\n\nFind models with search, then inspect structure with show, fields, indexes or profile. Use select for a single-model preview, query for aggregation and joins, export for CSV files, and field-profile for field statistics.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Explore model data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.search.summary": "Search semantic models.",
-	"cli.cmd.model.search.desc": "Search visible .tbl semantic models by full path or by combinable location, model-property, and field-property filters.",
+	"cli.cmd.model.search.desc": "Search visible .tbl semantic models by full path or by combinable location, model-property, and field-property filters.\n\nUse returned .tbl paths with subsequent model commands. See the parameters below for exact-path lookup and combined filters. Results contain only visible models; reaching the limit does not mean no other models exist.",
 	"cli.cmd.model.search.query": "Starts with '/': full model path or path glob. Contains '*' or '?': model file name glob. Otherwise broadly searches model metadata or visible field metadata by keyword.",
 	"cli.cmd.model.search.path": "Search by an absolute model metadata path glob; a project root searches recursively. Can be combined with a keyword <query>, but not with a path <query>, --project, --parent-dir, or --name.",
 	"cli.cmd.model.search.name": "Search by a model file name glob; without wildcards, matches exactly. Can be combined with a keyword <query>, --project, and --parent-dir, but not with a glob <query> or --path.",
@@ -1462,11 +1535,11 @@
 	"cli.cmd.model.search.nameHint": "Model names match exactly without wildcards; wildcards and the .tbl suffix are not added automatically.",
 	"cli.cmd.model.search.hasMore": "Only the {0} most relevant models are shown; add a project, directory, type, or more specific keyword to narrow the search.",
 	"cli.cmd.model.show.summary": "Show model metadata summary.",
-	"cli.cmd.model.show.desc": "Show semantic model metadata summary.",
+	"cli.cmd.model.show.desc": "Show semantic model metadata summary.\n\nUse a .tbl path returned by search for <model>. Use fields for columns and profile --json for full metadata and row counts. This command does not query model rows.",
 	"cli.cmd.model.profile.summary": "Profile one semantic model.",
-	"cli.cmd.model.profile.desc": "Return the model summary, current full metadata, and physical table row count. Human output is concise; use --json for the full metadata.",
+	"cli.cmd.model.profile.desc": "Return the model summary, current full metadata, and physical table row count. Human output is concise; use --json for the full metadata.\n\nRow counting accesses the data source and may be affected by permissions or connectivity. Check dataRowCount.value or errorInfo; missing or failed statistics are not zero. Use field-profile for field-level statistics.",
 	"cli.cmd.model.fieldProfile.summary": "Profile selected model fields.",
-	"cli.cmd.model.fieldProfile.desc": "Inspect selected fields, inferred analytical roles, dimension attributes, and optional data statistics. Select 1 to 20 fields; aliases resolving to the same fieldPath are deduplicated.\n\nCapability depends on field type, data source, data volume, permissions, and masking. nullCount/nullRate apply to queryable fields. Numeric fields can use distinctCount, minValue, maxValue, sum, avg, zeroCount, negativeCount, topValues, and sampleValues. String/date fields can use distinctCount, minValue, maxValue, topValues, and sampleValues; boolean fields can use distinctCount, topValues, and sampleValues. median, p90, and p95 are accepted for protocol compatibility but currently return unsupported. Check dataProfile.unavailableProperties for the actual result. For unknown-size models, distinctCount/topValues run only after the visible row count is confirmed at 100,000 or less; million-scale models return costLimit. JSON sum/avg values are decimal strings to preserve precision.",
+	"cli.cmd.model.fieldProfile.desc": "Inspect selected fields, inferred analytical roles, dimension attributes, and optional data statistics. Select 1 to 20 fields; aliases resolving to the same fieldPath are deduplicated.\n\nCapability depends on field type, data source, data volume, permissions, and masking. nullCount/nullRate apply to queryable fields. Numeric fields can use distinctCount, minValue, maxValue, sum, avg, zeroCount, negativeCount, topValues, and sampleValues. String/date fields can use distinctCount, minValue, maxValue, topValues, and sampleValues; boolean fields can use distinctCount, topValues, and sampleValues. median, p90, and p95 are accepted for protocol compatibility but currently return unsupported. Check dataProfile.unavailableProperties for the actual result. For unknown-size models, distinctCount/topValues run only after the visible row count is confirmed at 100,000 or less; million-scale models return costLimit. JSON sum/avg values are decimal strings to preserve precision.\n\nUse model fields to identify field paths first. For structure only, use --no-data, which cannot be combined with --data-property. Request only the statistics needed to reduce query cost.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Explore model data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.fieldProfile.field": "Field physical name, business name, or fieldPath. Repeat to select up to 20 fields; equivalent names are deduplicated by fieldPath.",
 	"cli.cmd.model.fieldProfile.dataProperty": "Data statistic to calculate. Repeat or use comma-separated values. Values: nullCount, nullRate, distinctCount, minValue, maxValue, sum, avg, median, p90, p95, zeroCount, negativeCount, topValues, sampleValues. Without this option, calculates nullCount, nullRate, distinctCount, minValue, and maxValue.",
 	"cli.cmd.model.fieldProfile.noData": "Do not scan field data; return semantic and dimension information only. Cannot be combined with --data-property.",
@@ -1474,14 +1547,14 @@
 	"cli.cmd.model.fieldProfile.sampleLimit": "Maximum sampleValues entries. Defaults to 10; valid range is 1 to 50.",
 	"cli.cmd.model.fieldProfile.dimensionAttributeDepth": "Dimension-attribute expansion depth. Defaults to 1; valid range is 0 to 3.",
 	"cli.cmd.model.fields.summary": "List model fields.",
-	"cli.cmd.model.fields.desc": "List semantic model fields.",
+	"cli.cmd.model.fields.desc": "List semantic model fields.\n\nUse a .tbl path returned by search. Base query field names on the returned field metadata; use field-profile when you need value distributions or statistics.",
 	"cli.cmd.model.fields.all": "Include hidden fields and extended properties.",
 	"cli.cmd.model.fields.contains": "Match fields by name, title, or database field. Plain text uses case-insensitive contains; /pattern/flags uses regex with i, m, and g (compatibility only; no effect).",
 	"cli.cmd.model.fields.dim": "Only list dimension-key fields.",
 	"cli.cmd.model.fields.measure": "Only list measure fields.",
 	"cli.cmd.model.fields.empty": "No matching fields found.",
 	"cli.cmd.model.indexes.summary": "List model indexes.",
-	"cli.cmd.model.indexes.desc": "List primary keys, business keys, and model indexes.",
+	"cli.cmd.model.indexes.desc": "List primary keys, business keys, and model indexes.\n\nUse a .tbl path returned by search. Results describe model key and index declarations; they do not verify data uniqueness. This command does not create or rebuild database indexes.",
 	"cli.cmd.model.indexes.empty": "This model has no indexes.",
 	"cli.cmd.model.*.select": "Select fields, separated by commas. Can be repeated.",
 	"cli.cmd.model.*.maxRows": "Maximum preview row count.",
@@ -1489,20 +1562,21 @@
 	"cli.cmd.model.*.queryFile": "Read Query DSL JSON from a file.",
 	"cli.cmd.model.*.stdin": "Read Query DSL JSON from stdin.",
 	"cli.cmd.model.select.summary": "Select rows from one model.",
-	"cli.cmd.model.select.desc": "Select rows from one .tbl model with SuccApp expression filters.",
+	"cli.cmd.model.select.desc": "Select rows from one .tbl model with SuccApp expression filters.\n\nInspect fields first. --where accepts a SuccApp expression, not a complete SQL statement. --max-rows limits preview rows. Use query for aggregation or joins, and export to save CSV.\n\nThe accompanying server defaults to a 100-row preview with a 1000-row cap. Actual behavior depends on the target server and returned truncation information. Use the corresponding export command for full data.",
 	"cli.cmd.model.select.where": "Filter expression, for example STATUS='ACTIVE'.",
 	"cli.cmd.model.select.order": "Sort expression, for example CREATE_TIME desc.",
 	"cli.cmd.model.select.limit": "Maximum returned row count.",
 	"cli.cmd.model.query.summary": "Query models with Query DSL.",
-	"cli.cmd.model.query.desc": "Query one or more .tbl models with Query DSL JSON.\n\nJSON type: succ.meta.dw.Query in query.d.ts.\nOnline DTS: https://docs.succapp.com/dev-types/types/meta/file-types/query.d.ts\nWorkspace DTS: .agents/skills/succapp-docs/dev-types/types/meta/file-types/query.d.ts",
+	"cli.cmd.model.query.desc": "Query one or more .tbl models with Query DSL JSON for aggregation or multi-model joins. This command runs a model query on the target server; it is not used to write model data.\n\nProvide exactly one of --query, --query-file, or --stdin. --max-rows must be an integer of at least 1. Results may be limited in row count and must not be assumed to contain all data.\n\nThe query JSON type is succ.meta.dw.Query in query.d.ts. Before writing a complex query, read the aggregation, multi-model query, and export sections in the guide below and consult the type definition. Check that these resources apply to your CLI and server versions; when offline, use an available matching manual.\n\nThe accompanying server defaults to a 100-row preview with a 1000-row cap. Actual behavior depends on the target server and returned truncation information. Use the corresponding export command for full data.\n\nDocumentation: Explore model data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-model-data\n\nType definition: succ.meta.dw.Query\nOnline: https://docs.succapp.com/dev-types/types/meta/file-types/query.d.ts\nLocal: .agents/skills/succapp-docs/dev-types/types/meta/file-types/query.d.ts",
 	"cli.cmd.model.query.empty": "Query succeeded; 0 rows returned.",
 	"cli.cmd.model.export.summary": "Export model query results as CSV.",
-	"cli.cmd.model.export.desc": "Export one model or Query DSL result as CSV.",
+	"cli.cmd.model.export.desc": "Export one model or Query DSL result as CSV.\n\nChoose <model> or one Query DSL input (--query, --query-file, --stdin), and specify a local CSV with --output. --select, --where and --order apply to single-model mode. Overwriting an existing file requires --force. Query conditions, DSL limits and access permissions still apply.\n\nFor the full workflow, consult the guide below and confirm it applies to your CLI and server version.\n\nGuide: Explore model data\nMarkdown: https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\nWeb: https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.export.where": "Filter expression for single-model export.",
 	"cli.cmd.model.export.order": "Sort expression for single-model export.",
 	"cli.cmd.model.export.output": "Write CSV output to a local file.",
 	"cli.cmd.model.export.force": "Overwrite the output file if it already exists.",
 	"cli.cmd.model.export.exportedData": "Exported data to {0}",
+	"cli.cmd.model.*.model": "A .tbl model path returned by model search, e.g. /DEMO/data/tables/customer.tbl.",
 	"vs.cmd.title.addServer": "Add Server",
 	"vs.cmd.title.useServer": "Use Server",
 	"vs.cmd.title.loginServer": "Login Server",