fix: align skills docs with current nb cli

chenos · chenos · commit 860856f764e0 · 2026-04-29T14:33:46.000+08:00
diff --git a/skills/nocobase-acl-manage/SKILL.md b/skills/nocobase-acl-manage/SKILL.md
@@ -225,18 +225,18 @@ Default behavior when user says `you decide`:
 - never execute write commands with uncertain, unresolved, or type-mismatched parameters
 - lock execution base-dir before any ACL discovery/write (use one stable project root for the whole task)
 - run execution guard sequence before ACL writes:
-- `nb env list -s project`
+- `nb env list`
 - `nb env update <current_env_name>`
 - `nb api acl --help`
 - `nb api acl roles --help`
 - fail-closed policy:
 - if `nb api acl --help` or `nb api acl roles --help` fails, stop and return capability-boundary message; do not switch to ad-hoc script execution.
-- confirm current env context through direct CLI: run `nb env list -s project` and resolve current env from the row marked with `*`
-- if no env is configured/current, stop writes and ask user whether to add/switch env using direct CLI (`nb env add ...` or `nb env use ... -s project`)
+- confirm current env context through direct CLI: run `nb env list` and resolve current env from the row marked with `*`
+- if no env is configured/current, stop writes and ask user whether to add/switch env using direct CLI (`nb env add ...` or `nb env use ...`)
 - if runtime command cache is missing/stale or command schema changed, run `nb env update <current_env_name>`
 - if runtime refresh fails with `swagger:get` 404 or API documentation plugin errors, activate dependency bundle and retry:
-- `nb pm enable @nocobase/plugin-api-doc`
-- `nb pm enable @nocobase/plugin-api-keys`
+- `nb plugin enable @nocobase/plugin-api-doc`
+- `nb plugin enable @nocobase/plugin-api-keys`
 - restart app before retrying runtime refresh
 - if token is missing/invalid, ensure `@nocobase/plugin-api-keys` is active and refresh token env first
 - resolve runtime command names via [intent-to-tool-map-v1](references/intent-to-tool-map-v1.md) and command help discovery
@@ -315,10 +315,10 @@ When a scenario is not supported by current CLI/runtime/tool policy:
 
 - task normalized to canonical task
 - required inputs complete before writes
-- CLI capability gate passes (env context available via direct `nb env list -s project`, runtime commands resolvable)
+- CLI capability gate passes (env context available via direct `nb env list`, runtime commands resolvable)
 - CLI dependency plugins (`@nocobase/plugin-api-doc`, `@nocobase/plugin-api-keys`) are active or explicit recovery guidance is emitted
 - runtime command names resolved from command map/help
-- execution guard evidence includes locked `base-dir` plus `nb env list -s project`, `nb env update <current_env_name>`, `nb api acl --help`, and `nb api acl roles --help`
+- execution guard evidence includes locked `base-dir` plus `nb env list`, `nb env update <current_env_name>`, `nb api acl --help`, and `nb api acl roles --help`
 - every write has immediate readback evidence
 - for `permission.data-source.resource.set`, data source + resolved collections + actions + scope were confirmed before write
 - when user did not provide scope, confirmation/readback shows `all` as the applied default scope
diff --git a/skills/nocobase-acl-manage/references/_archive/scopes.md b/skills/nocobase-acl-manage/references/_archive/scopes.md
@@ -140,7 +140,7 @@ Common scope-related CLI commands:
 - `data_sources_roles_resources_scopes_update`
 - `data_sources_roles_resources_scopes_destroy`
 
-All calls should use resolved `nb` runtime commands through direct nb CLI (`nb <command> [subcommand ...] [flags ...]`) discovered from CLI help, after env context is confirmed by `nb env list -s project`.
+All calls should use resolved `nb` runtime commands through direct nb CLI (`nb <command> [subcommand ...] [flags ...]`) discovered from CLI help, after env context is confirmed by `nb env list`.
 
 Business rules:
 
@@ -174,4 +174,3 @@ Recommended usage:
 - `own` does not mean owner, assignee, approver, manager, or department member
 - for those semantics, create a custom scope and reference `$user` against real business relation paths
 
-
diff --git a/skills/nocobase-acl-manage/references/configuration.md b/skills/nocobase-acl-manage/references/configuration.md
@@ -373,11 +373,10 @@ Use CLI command contracts when auditing results. Do not fallback to direct HTTP
 4. `roles_data_source_resources_get`
 5. `data_sources_roles_resources_scopes_get` or `data_sources_roles_resources_scopes_list`
 
-All checks above should be executed through resolved CLI runtime commands via direct nb CLI (`nb <command> [subcommand ...] [flags ...]`) and command help discovery, with env context resolved first by `nb env list -s project`.
+All checks above should be executed through resolved CLI runtime commands via direct nb CLI (`nb <command> [subcommand ...] [flags ...]`) and command help discovery, with env context resolved first by `nb env list`.
 
 For scoped actions, do not rely only on appended `actions.scope` payloads. Prefer:
 
 - read the resource action and record its `scopeId`
 - read the target scope record separately by id
 
-
diff --git a/skills/nocobase-acl-manage/references/execution-guard-template.md b/skills/nocobase-acl-manage/references/execution-guard-template.md
@@ -17,15 +17,15 @@ Use this template before any ACL write (for example `role.create-blank`, role mo
 ## Guard Sequence (Mandatory)
 
 ```bash
-nb env list -s project
+nb env list
 nb env update <current_env_name>
 nb api acl --help
 nb api acl roles --help
 ```
 
 Pass criteria:
 
-- `env list -s project` returns an active project env (`*` row).
+- `env list` returns an active env (`*` row).
 - `env update <current_env_name>` succeeds or returns actionable recovery guidance.
 - `nb api acl --help` resolves successfully.
 - `nb api acl roles --help` resolves successfully and lists role lifecycle commands (`create/get/list/update/destroy`).
@@ -76,7 +76,7 @@ nb api acl roles get --filter-by-tk <role_name> -j
 ```text
 execution_guard:
 - base_dir: <acl_base_dir>
-- env_project_scope: <summary of env list -s project>
+- env_current_state: <summary of env list>
 - env_update: pass|fail
 - acl_help: pass|fail
 - acl_roles_help: pass|fail
diff --git a/skills/nocobase-acl-manage/references/intent-to-tool-map-v1.md b/skills/nocobase-acl-manage/references/intent-to-tool-map-v1.md
@@ -20,7 +20,7 @@ Execute ACL commands through direct nb CLI:
 
 Resolve current env context through direct CLI:
 
-- `nb env list -s project` (resolve current env from row marked with `*`)
+- `nb env list` (resolve current env from row marked with `*`)
 
 ## Runtime Command Discovery
 
@@ -29,15 +29,15 @@ Because runtime commands are generated from swagger, command names can vary by b
 Prerequisite gate before runtime discovery:
 
 0. Lock one `base-dir` for the whole task (do not switch base-dir mid-task).
-1. Run `nb env list -s project` to get `current_env_name` from the `*` row.
+1. Run `nb env list` to get `current_env_name` from the `*` row.
 2. If there is no current env, add/use one first:
-   - local URL: `nb env add <env> --scope project --api-base-url <local_url>/api --auth-type oauth`
-   - remote URL (token): `nb env add <env> --scope project --api-base-url <remote_url>/api --auth-type token --access-token <token>`
-   - switch: `nb env use <env> -s project`
+   - local URL: `nb env add <env> --api-base-url <local_url>/api --auth-type oauth`
+   - remote URL (token): `nb env add <env> --api-base-url <remote_url>/api --auth-type token --access-token <token>`
+   - switch: `nb env use <env>`
 3. Run `nb env update <current_env_name>`.
 4. If output shows `swagger:get` 404 or API documentation plugin error, activate dependency bundle and retry:
-   - `nb pm enable @nocobase/plugin-api-doc`
-   - `nb pm enable @nocobase/plugin-api-keys`
+   - `nb plugin enable @nocobase/plugin-api-doc`
+   - `nb plugin enable @nocobase/plugin-api-keys`
    - restart app before rerun.
 5. If output shows `401/403/Auth required`, ensure `@nocobase/plugin-api-keys` is active and refresh token env first.
 6. If `nb api acl --help` or `nb api acl roles --help` still fails in this same `base-dir`, fail closed:
diff --git a/skills/nocobase-acl-manage/references/refactor-plan-v2.md b/skills/nocobase-acl-manage/references/refactor-plan-v2.md
@@ -66,13 +66,13 @@ Current transport strategy is CLI-first:
 CLI capability gate requires:
 
 - direct nb CLI exists (`nb`) and `node` exists
-- current env is available via direct CLI (`nb env list -s project`; switch/add through `nb env use` / `nb env add`)
+- current env is available via direct CLI (`nb env list`; switch/add through `nb env use` / `nb env add`)
 - runtime commands are available (`nb env update` when needed)
 - `@nocobase/plugin-api-doc` is active so `swagger:get` can provide runtime command schema
 - `@nocobase/plugin-api-keys` is active so token bootstrap/refresh can recover auth failures
 - recovery command for missing dependencies:
-- `nb pm enable @nocobase/plugin-api-doc`
-- `nb pm enable @nocobase/plugin-api-keys`
+- `nb plugin enable @nocobase/plugin-api-doc`
+- `nb plugin enable @nocobase/plugin-api-keys`
 
 ## 4. Current Constraints
 
diff --git a/skills/nocobase-acl-manage/tests/README.md b/skills/nocobase-acl-manage/tests/README.md
@@ -14,7 +14,7 @@ This folder tracks runtime verification for `nocobase-acl-manage` v2.
 ```bash
 cd <BASE_DIR>
 nb --help
-nb env list -s project
+nb env list
 nb env update <ENV_NAME>  # use current env from the `*` row
 nb api acl --help
 nb api acl roles --help
@@ -23,11 +23,11 @@ nb api acl roles --help
 2. If env context is missing, recover through direct CLI:
 
 ```bash
-nb env list -s project
+nb env list
 # add env when missing
-nb env add <ENV_NAME> --scope project --api-base-url <BASE_URL>/api --auth-type oauth
+nb env add <ENV_NAME> --api-base-url <BASE_URL>/api --auth-type oauth
 # or switch to existing env
-nb env use <ENV_NAME> -s project
+nb env use <ENV_NAME>
 ```
 
 If needed, follow with add/use actions before continuing ACL tests.
diff --git a/skills/nocobase-acl-manage/tests/capability-test-plan.md b/skills/nocobase-acl-manage/tests/capability-test-plan.md
@@ -25,8 +25,8 @@ Excluded:
 
 | ID | Domain | Capability | Validation Mode |
 |---|---|---|---|
-| ACL-SMOKE-001 | cli | `nb --help` + `nb env list -s project` availability | runtime |
-| ACL-SMOKE-002 | cli | execution guard fail-closed check (`env list -s project`, `env update`, `nb api acl --help`, `nb api acl roles --help`) in one locked base-dir | runtime |
+| ACL-SMOKE-001 | cli | `nb --help` + `nb env list` availability | runtime |
+| ACL-SMOKE-002 | cli | execution guard fail-closed check (`env list`, `env update`, `nb api acl --help`, `nb api acl roles --help`) in one locked base-dir | runtime |
 | ACL-ROLE-001 | role | create blank role | runtime |
 | ACL-ROLE-002 | role | audit roles read chain | runtime |
 | ACL-GLOBAL-001 | global-role-mode | read current global role mode | runtime |
@@ -56,7 +56,7 @@ Excluded:
 Required:
 
 - `nb` CLI available in PATH
-- direct env commands available (`nb env list -s project`, `nb env use`, `nb env add`)
+- direct env commands available (`nb env list`, `nb env use`, `nb env add`)
 - configured current env context and token (when remote env requires it)
 - `@nocobase/plugin-api-doc` active (`swagger:get` available for runtime command discovery)
 - `@nocobase/plugin-api-keys` active (token generation/refresh recovery path)
diff --git a/skills/nocobase-acl-manage/tests/test-playbook.md b/skills/nocobase-acl-manage/tests/test-playbook.md
@@ -165,7 +165,7 @@ Runtime Command:
 ```bash
 cd <BASE_DIR>
 nb --help
-nb env list -s project
+nb env list
 nb env update <ENV_NAME>
 ```
 
@@ -187,7 +187,7 @@ Runtime Command:
 
 ```bash
 cd <WRONG_BASE_DIR>
-nb env list -s project
+nb env list
 nb api acl --help
 nb api acl roles --help
 ```
diff --git a/skills/nocobase-env-manage/SKILL.md b/skills/nocobase-env-manage/SKILL.md
@@ -135,7 +135,7 @@ For `current`, derive from the row marked with leading `*` in `nb env list` outp
 When CLI returns:
 
 - `No envs configured.`
-- `Run 'nb env add <name> --base-url <url>' to add one.`
+- `Run 'nb env add <name> --api-base-url <url>' to add one.`
 
 surface this message directly and ask whether to create a new app (`nb init --ui`) or add env.
 
diff --git a/skills/nocobase-env-manage/agents/openai.yaml b/skills/nocobase-env-manage/agents/openai.yaml
@@ -62,7 +62,7 @@ interface:
 
     If `nb env list` reports:
     - `No envs configured.`
-    - `Run 'nb env add <name> --base-url <url>' to add one.`
+    - `Run 'nb env add <name> --api-base-url <url>' to add one.`
     relay this to user directly and ask whether to create a new app (`nb init --ui`) or add env.
 
     Output should include executed command, relevant CLI outputs, and normalized API base URL when `env add` is used.
diff --git a/skills/nocobase-publish-manage/SKILL.md b/skills/nocobase-publish-manage/SKILL.md
@@ -23,13 +23,11 @@ Supported scenarios:
 
 - Feishu wiki: `https://nocobase.feishu.cn/wiki/M0knwAvYSiAouUk1ZHAcduDjnmh`
 
-Command examples from that direction:
+Current status against the latest local CLI:
 
-- `nb backup list --env <env>`
-- `nb restore <file-name> --env <env>`
-- `nb migration rule add --env <env>`
-- `nb migration generate <ruleId> --env <env>`
-- `nb migration run <file-name> --env <env>`
+- The current `nb` CLI in this repo does not expose top-level `backup`, `restore`, or `migration` commands.
+- Treat publish operations as capability-gated. Always verify with `nb --help` first.
+- If the required publish command family is absent, stop and return the capability-boundary message instead of fabricating a fallback command.
 
 # Hard Rules
 
@@ -73,29 +71,26 @@ Single or cross environment are both supported by env arguments.
 Recommended sequence:
 
 ```bash
-nb backup list --env <source_env>
-nb restore <backup_file> --env <target_env>
+Blocked on current CLI unless a newer `nb` build restores top-level `backup` / `restore`.
 ```
 
 Rules:
 
-- if `backup_file` is missing, stop after `backup list` and ask user to choose one file
-- require `confirm=confirm` before `restore`
+- if the CLI does not expose `backup` / `restore`, stop immediately with the capability-boundary message
+- require `confirm=confirm` before `restore` when this command family becomes available again
 
 ## publish with `migration`
 
 Recommended sequence:
 
 ```bash
-nb migration rule add --env <source_env>
-nb migration generate <rule_id> --env <source_env>
-nb migration run <migration_file> --env <target_env>
+Blocked on current CLI unless a newer `nb` build restores top-level `migration` commands.
 ```
 
 Rules:
 
-- if `rule_id` missing, stop and ask user to create/select rule first
-- if `migration_file` missing after generate step, stop and ask user to confirm package
+- if the CLI does not expose `migration`, stop immediately with the capability-boundary message
+- if `rule_id` or `migration_file` is missing after future support lands, stop and ask the user to choose the missing input
 - require `confirm=confirm` before `migration run`
 
 # Safety
@@ -109,8 +104,8 @@ Rules:
 - Skill does not reference local script entrypoints.
 - Skill executes publish command directly without precheck.
 - Missing commands produce `developing` response and no mutation command runs.
-- Backup restore flow uses `nb backup list` + `nb restore`.
-- Migration flow uses `nb migration rule add/generate/run`.
+- Backup restore flow is currently blocked unless a future `nb` build reintroduces the required commands.
+- Migration flow is currently blocked unless a future `nb` build reintroduces the required commands.
 
 # Output Contract
 
diff --git a/skills/nocobase-publish-manage/agents/openai.yaml b/skills/nocobase-publish-manage/agents/openai.yaml
@@ -12,7 +12,7 @@ agent:
     - migration
 
     Prefer executing user-requested publish commands first.
-    Use capability/help commands (`nb --help`, `nb backup --help`, `nb migration --help`) when diagnostics/help output or command discovery is needed.
+    Use capability/help commands (`nb --help`) when diagnostics/help output or command discovery is needed.
     Execute the target command directly and follow CLI output.
     If CLI reports command-not-found/unknown-command/not-supported, stop and return:
     - `feature_status=developing`
@@ -21,9 +21,9 @@ agent:
 
     Command mapping:
     - backup_restore publish:
-      `nb backup list --env <source_env>` -> `nb restore <backup_file> --env <target_env>`
+      blocked on current CLI unless a newer build restores top-level `nb backup` / `nb restore`
     - migration publish:
-      `nb migration rule add --env <source_env>` -> `nb migration generate <rule_id> --env <source_env>` -> `nb migration run <migration_file> --env <target_env>`
+      blocked on current CLI unless a newer build restores top-level `nb migration` commands
 
     Safety:
     - Require explicit `confirm=confirm` before publish mutations (`restore` / `migration run`).
diff --git a/skills/nocobase-publish-manage/references/test-playbook.md b/skills/nocobase-publish-manage/references/test-playbook.md
@@ -3,7 +3,7 @@
 ## Case 1: backup_restore direct execution when command missing
 
 ```bash
-nb backup list --env dev
+Blocked on current CLI: `nb backup list` is not available.
 ```
 
 Expected:
@@ -14,7 +14,7 @@ Expected:
 ## Case 2: migration direct execution when command missing
 
 ```bash
-nb migration rule add --env dev
+Blocked on current CLI: `nb migration rule add` is not available.
 ```
 
 Expected:
@@ -25,8 +25,7 @@ Expected:
 ## Case 3: backup_restore publish happy path (future-supported)
 
 ```bash
-nb backup list --env dev
-nb restore <backup_file> --env test
+Blocked on current CLI: `nb backup list` / `nb restore` are not available.
 ```
 
 Expected:
@@ -36,9 +35,7 @@ Expected:
 ## Case 4: migration publish happy path (future-supported)
 
 ```bash
-nb migration rule add --env dev
-nb migration generate <rule_id> --env dev
-nb migration run <migration_file> --env test
+Blocked on current CLI: `nb migration rule add` / `generate` / `run` are not available.
 ```
 
 Expected:
diff --git a/skills/nocobase-publish-manage/references/v1-runtime-contract.md b/skills/nocobase-publish-manage/references/v1-runtime-contract.md
@@ -2,13 +2,12 @@
 
 ## Scope
 
-This skill is nb CLI only and follows:
+This skill is nb CLI only.
 
-- `nb backup list`
-- `nb restore`
-- `nb migration rule add`
-- `nb migration generate`
-- `nb migration run`
+Current compatibility note:
+
+- The current local `nb` CLI does not expose top-level `backup`, `restore`, or `migration` commands.
+- Do not emit those commands unless a newer CLI build explicitly restores them in `nb --help`.
 
 ## Execution Rule
 
@@ -26,16 +25,13 @@ When any required command is unavailable (`Unknown command`), runtime must retur
 ### backup_restore
 
 ```bash
-nb backup list --env <source_env>
-nb restore <backup_file> --env <target_env>
+Blocked on current CLI: top-level `nb backup` / `nb restore` commands are absent.
 ```
 
 ### migration
 
 ```bash
-nb migration rule add --env <source_env>
-nb migration generate <rule_id> --env <source_env>
-nb migration run <migration_file> --env <target_env>
+Blocked on current CLI: top-level `nb migration` commands are absent.
 ```
 
 ## Mutation Gate
diff --git a/skills/nocobase-workflow-manage/references/cli/index.md b/skills/nocobase-workflow-manage/references/cli/index.md
@@ -35,7 +35,7 @@ nb api workflow jobs <subcommand> -h
 
 ## Invocation Conventions
 
-- Common connection flags are shared across commands: `--base-url`, `-e/--env`, `--role`, `-t/--token`, `-j/--json-output`.
+- Common connection flags are shared across commands: `--api-base-url`, `-e/--env`, `--role`, `-t/--token`, `-j/--json-output`.
 - Query parameters usually become kebab-case flags such as `--filter-by-tk`, `--page-size`, `--branch-index`, or `--workflow-id`.
 - Array query parameters are repeatable flags such as `--appends` and `--except`.
 - JSON fields expect JSON strings.
