@mu-cabin/coding-cli 0.1.0

package/skills/coding/references/permissions.md

@@ -0,0 +1,164 @@
+# coding-permissions
+
+A curated playbook for the **权限 (03)** category — the 25 authorization actions. The most
+*conceptual* category — get the model right and the actions fall out of it.
+
+## 1. The authorization model (RAM-style)
+
+A **grant** is a triple: a **grant object** (the principal) is given a **policy** (a permission set)
+**on a resource** (the target).
+
+- **Policy (权限组)** — a named permission set (`PolicyDocument` of `Statement[]`). Id: **`PolicyId`**
+  (int64). Has a `PolicyType` (`IDENTITY` | `RESOURCE`) and a read-only `Scope` (`SYSTEM` | `CUSTOM`).
+- **UserGroup (用户组)** — a named bag of users. Id: **`GroupId`** (int64). Just a container.
+- **GrantObject (授权对象)** — the principal receiving a grant. Identified by **`GrantObjectId`
+  (a *string*)** + its type field **`GrantScope`** ∈ `USER` | `USER_GROUP` | `DEPARTMENT`.
+  (There is **no** `GrantObjectType` field — the type is `GrantScope`.)
+- **Resource** — the target, a `(ResourceType, ResourceId)` pair. `ResourceType` is a free **string**
+  (e.g. `project`, `team`, `depot`), `ResourceId` is a **string**.
+
+So a grant ≈ `{GrantObjectId, GrantScope, PolicyId}` (a **`GrantInfo`**) applied to a `{ResourceType,
+ResourceId}` (a **`Resource`**).
+
+> ⚠️ **Three different "resource" shapes** — pass the right one:
+> - **`ResourceInfo`** (full: `ResourceType`,`ResourceId` + optional `ResourceScope`/`ServiceName`/`RelativeResource`)
+>   — used by the grant verbs, `DescribeGrantObjectsOnResource`, the predicate actions, `DescribeUsersOnResourceAndGrantObject`.
+> - **`ResourceInfoOfPolicyScope`** (minimal: just `ResourceType`,`ResourceId`) — used by the
+>   resource-scope-on-policy actions and `DescribeAvailablePoliciesOnResource`.
+> - **`RamGrantResourceInfoRequest`** (also just `ResourceType`,`ResourceId`) — **only**
+>   `DescribeGrantUsersOnResource`. Don't pass `ServiceName`/`ResourceScope` where the minimal shape is expected.
+
+## 2. Granting & revoking on a resource — three verbs, different semantics
+
+All three take **`Resource`** (a `ResourceInfo`) + **`Grants`** (an Array of `GrantInfo`). The difference
+is what they do to *existing* grants:
+
+```bash
+# additive — appends the listed grants; existing ones untouched; duplicates skipped
+coding call AttachToResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "Grants":[{"GrantObjectId":"5","GrantScope":"USER","PolicyId":3001}]}' --json
+
+# selective revoke — removes ONLY the listed grants; other grants untouched
+coding call DetachFromResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "Grants":[{"GrantObjectId":"5","GrantScope":"USER","PolicyId":3001}]}' --json
+
+# replace-all FOR THAT PRINCIPAL — ⚠️ first revokes ALL of the grant object's existing grants on the
+# resource, then sets exactly what you pass. Semantically destructive (see §6).
+coding call SetGrantToResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "Grants":[{"GrantObjectId":"5","GrantScope":"USER","PolicyId":3001}]}' --json
+```
+
+Inspect who has access to a resource:
+
+```bash
+# grant OBJECTS on a resource (users / groups / departments) → Data.GrantObjectList[]
+coding call DescribeGrantObjectsOnResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "PageNumber":1,"PageSize":50}' --select 'Data.GrantObjectList[].GrantScope,Data.GrantObjectList[].GrantObjectId,Data.GrantObjectList[].GrantObjectName' --json
+
+# effective USERS on a resource (flattens groups/departments to their users) → Data.UserDataList[]
+#   NOTE: this one uses the minimal RamGrantResourceInfoRequest resource shape.
+coding call DescribeGrantUsersOnResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "PageNumber":1,"PageSize":50}' --select 'Data.UserDataList[].Id,Data.UserDataList[].Name,Data.UserDataList[].Email' --json
+
+# users contributed by ONE specific grant object on a resource — note singular `Grant` (object, not array)
+coding call DescribeUsersOnResourceAndGrantObject --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},
+  "Grant":{"GrantObjectId":"7","GrantScope":"USER_GROUP"},"PageNumber":1,"PageSize":50}' --select 'Data.UserDataList[].Id,Data.UserDataList[].Name' --json
+```
+
+## 3. Permission groups (权限组 / Policy)
+
+```bash
+# list policies applicable to a resource TYPE (Filter.ResourceType required) → Data.PolicyList[]
+coding call DescribePoliciesOnResourceType --data '{"Filter":{"ResourceType":"project"},"PageNumber":1,"PageSize":50}' \
+  --select 'Data.PolicyList[].PolicyId,Data.PolicyList[].Name,Data.PolicyList[].Alias,Data.PolicyList[].PolicyType' --json
+
+# list policies available on a specific resource → Data.PolicyList[].
+#   ⚠️ Filter is REQUIRED here (pass {} for none; or {"PolicyAlias":"…","Visible":"true"}).
+coding call DescribeAvailablePoliciesOnResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},"Filter":{},"PageNumber":1,"PageSize":50}' \
+  --select 'Data.PolicyList[].PolicyId,Data.PolicyList[].Alias' --json
+
+# detail — ⚠️ result is at top-level `PolicyInfo`, NOT under Data
+coding call DescribePolicy --param PolicyId=3001 --param AccurateActions=true --select 'PolicyInfo.Name,PolicyInfo.Alias,PolicyInfo.PolicyDocument' --json
+
+# create: PolicyDocument is Statement[] of {Effect ALLOW|DENY, Action[], Resource[]}. ResourceType is an ARRAY here.
+coding call CreatePolicy --data '{"Name":"depot-reader","Alias":"Depot reader","PolicyType":"RESOURCE","ResourceType":["depot"],
+  "PolicyDocument":{"Statement":[{"Effect":"ALLOW","Action":["ram:DescribeDepot"],"Resource":["*"]}]}}' --json   # → PolicyId
+
+# modify — ⚠️ the id field is `Id`, not `PolicyId`; ResourceType still an array
+coding call ModifyPolicy --data '{"Id":3001,"ResourceType":["depot"],"PolicyDocument":{"Statement":[{"Effect":"ALLOW","Action":["ram:DescribeDepot","ram:PushDepot"],"Resource":["*"]}]}}' --json
+```
+
+## 4. User groups (用户组)
+
+```bash
+coding call DescribeUserGroups --data '{"Filter":{"GroupName":"qa"},"PageNumber":1,"PageSize":50}' \
+  --select 'Data.UserGroupList[].Id,Data.UserGroupList[].Name,Data.UserGroupList[].Description' --json
+coding call DescribeUsersByGroupId --param GroupId=70 --param PageNumber=1 --param PageSize=50 \
+  --select 'Data.UserDataList[].Id,Data.UserDataList[].Name,Data.UserDataList[].Email' --json
+
+coding call CreateUserGroup --data '{"Name":"QA team","Description":"quality engineers"}' --json   # → Id
+coding call UpdateUserGroupById --data '{"GroupId":70,"Name":"QA team","Description":"quality + automation"}' --json
+
+# add / remove specific (user,group) pairs — UserGroupUserInfos is an array of {UserId,GroupId}
+coding call CreateUserGroupUsers --data '{"UserGroupUserInfos":[{"UserId":254,"GroupId":70}]}' --json
+coding call DeleteUserGroupUsers --data '{"UserGroupUserInfos":[{"UserId":254,"GroupId":70}]}' --yes --json   # destructive
+```
+
+## 5. A policy's resource scope (which resources it may be applied to)
+
+Separate from grants: this controls the set of resources a policy is *allowed to target*.
+
+```bash
+coding call DescribeResourceScopeListOnPolicy --param PolicyId=3001 --param PageNumber=1 --param PageSize=50 \
+  --select 'Data.PolicyResourceScopeList[].Resource.ResourceType,Data.PolicyResourceScopeList[].Resource.ResourceId' --json
+
+# additive — `ResourceInfos` (plural, minimal shape). DetachResourceScopeOnPolicy is the selective remove.
+coding call AttachResourceScopeToPolicy --data '{"PolicyId":3001,"ResourceInfos":[{"ResourceType":"project","ResourceId":"102"}]}' --json
+coding call DetachResourceScopeOnPolicy --data '{"PolicyId":3001,"ResourceInfos":[{"ResourceType":"project","ResourceId":"102"}]}' --json
+```
+
+## 6. Permission-inheritance / 判定策略 (predicate policy)
+
+Per-resource, controls how effective permissions are *computed* relative to the parent resource.
+
+```bash
+# read — ⚠️ result at top-level `PredicatePolicyOnResourceInfo`, NOT under Data
+coding call DescribePredicatePolicyOnResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"}}' \
+  --select 'PredicatePolicyOnResourceInfo.ResourcePredicatePolicy,PredicatePolicyOnResourceInfo.HasAdministrator' --json
+
+# set — ResourcePredicatePolicy ∈ SELF_PARENT (parent + self) | SELF_NONE (self only) | NONE_PARENT (parent only)
+coding call SetPredicatePolicyOnResource --data '{"Resource":{"ResourceType":"project","ResourceId":"102"},"ResourcePredicatePolicy":"SELF_PARENT"}' --json
+```
+
+## 7. Destructive actions (exit-10 gated)
+
+Four `Delete*` actions need `--yes` (preview with `--dry-run`, get explicit approval, re-run the **same
+argv with `--yes`** — see SKILL.md's exit-10 protocol):
+
+- **`DeletePoliciesById`** — `Id` is an **Array** of policy ids.
+- **`DeleteUserGroupByIds`** — `GroupIds` is an **Array** of group ids.
+- **`DeleteUserGroupUsers`** — removes specific `{UserId,GroupId}` pairs.
+- **`DeleteAllUsersOnGroup`** — clears **all** users from one `GroupId` (irreversible membership wipe).
+
+> ⚠️ **`SetGrantToResource` is only classified `write`, but it is semantically destructive** — it revokes
+> all of the grant object's existing grants on the resource before applying yours. The exit-10 gate will
+> **not** stop it, so confirm the principal + resource with the user and prefer `AttachToResource` (additive)
+> or `DetachFromResource` (selective) unless a full replace is truly intended.
+
+## 8. Gotchas
+
+- **Id-field names are inconsistent.** Policy: `PolicyId` (create-result, `DescribePolicy`, inside
+  `GrantInfo`) but **`Id`** in `ModifyPolicy` and `DeletePoliciesById` (array). UserGroup: `Id`
+  (create-result) but `GroupId` in most actions and `GroupIds` (array) in `DeleteUserGroupByIds`.
+- **`GrantObjectId` and `ResourceId` are strings**, not integers, despite numeric content. The grant-object
+  *type* is **`GrantScope`** (`USER`|`USER_GROUP`|`DEPARTMENT`), not a `GrantObjectType` field.
+- **`ResourceType` is an Array of string only in `CreatePolicy`/`ModifyPolicy`**; everywhere else it's a
+  scalar string — nested inside a `Resource` object (the grant/scope verbs) or inside a `Filter` (the
+  `DescribePoliciesOnResourceType` / `DescribeResourceScopeListOnPolicy` reads).
+- **`DescribeUsersOnResourceAndGrantObject` uses `Grant` (a single object)**; the Attach/Set/Detach verbs
+  use `Grants` (an array). Easy to mix up.
+- **Two reads are NOT under `Data`**: `DescribePolicy` → `PolicyInfo`; `DescribePredicatePolicyOnResource`
+  → `PredicatePolicyOnResourceInfo`. All the list actions wrap under `Data.<XList>[]` (`PolicyList`,
+  `UserGroupList`, `UserDataList`, `GrantObjectList`, `PolicyResourceScopeList`) with paging under `Data`.
+- **Permission administration itself needs a high-scope token** — that's what an exit-8
+  `UnauthorizedOperation` means here (a scope gap, not a wrong token).

package/skills/coding/references/program.md

@@ -0,0 +1,79 @@
+# coding-program
+
+A curated playbook for the **项目集 / Program (05)** category — 6 actions. A *program* is a portfolio
+that groups multiple projects and carries its own membership/permissions.
+
+## 1. Identifiers
+
+- **`ProgramId`** (int64) is the program handle — what every program-scoped action takes. Get it from
+  `DescribePrograms` → `Data.Programs[].Id`.
+- A program also has **`Name`** (the slug / 标识) and **`DisplayName`** (展示名) — distinct fields, same
+  as projects. Member ops use the **permissions model**: a principal is (`PrincipalType`,
+  `PrincipalId`) and policies are named (`ProgramAdmin`, `ProgramMember`, …) or policy IDs.
+- **Everything wraps under `Data`** in this category (no top-level objects). Note: `DescribePrograms` →
+  `Data.Programs[]` (paged), but `DescribeProgramProjects` → `Data[]` is **itself the array**.
+
+> ⚠️ **There is no Delete/Modify-Program action** in the API surface — you can `CreateProgram` and add
+> projects/members, but renaming or deleting a program is **not** exposed here. Don't promise it.
+
+## 2. Find & read
+
+```bash
+# list/search programs (paging required; Keyword filters by name)
+coding call DescribePrograms --data '{"PageNumber":1,"PageSize":20,"Keyword":""}' \
+  --select 'Data.TotalCount,Data.Programs[].Id,Data.Programs[].Name,Data.Programs[].DisplayName' --json
+
+# the projects inside a program (Data is the array directly)
+coding call DescribeProgramProjects --param ProgramId=5 \
+  --select 'Data[].Id,Data[].Name,Data[].DisplayName' --json
+```
+
+## 3. Create & populate
+
+```bash
+# create a program — Description, DisplayName, EndDate, Name, StartDate are ALL required.
+#   Dates are "yyyy-MM-dd" strings on input (responses echo them back as epoch ints).
+#   WorkflowProgramId is optional (an existing workflow program's Id).
+coding call CreateProgram --data '{"Name":"platform","DisplayName":"Platform Portfolio",
+  "Description":"core platform work","StartDate":"2025-01-01","EndDate":"2025-12-31"}' \
+  --select 'Data.Id,Data.Name,Data.DisplayName' --json
+
+# add projects into the program — ProjectId is an ARRAY of numeric project ids
+coding call CreateProgramProjects --data '{"ProgramId":5,"ProjectId":[173,341]}' --json
+```
+
+## 4. Member permission policies
+
+A member's access to a program is a set of **policies** attached to a principal. `Create…` is additive;
+`Delete…` removes the listed policies (see §5). Both take the same shape.
+
+```bash
+# grant policies to a user within the program (PrincipalType USER; PrincipalId is a STRING)
+coding call CreateProgramMemberPolicy --data '{"ProgramId":5,"PrincipalType":"USER","PrincipalId":"4",
+  "Policies":["ProgramAdmin","ProgramMember"]}' --select 'Data[].PolicyId,Data[].PolicyName' --json
+```
+
+- `PrincipalType` is the principal kind — `USER` is the documented example value (the broader RAM
+  model also defines `USER_GROUP`/`DEPARTMENT`, but only `USER` is evidenced for this action);
+  `PrincipalId` is its **string** id.
+- `Policies` are default policy **names** (`ProgramAdmin`, `ProgramMember`, …) or policy IDs.
+
+## 5. Destructive action (exit-10 gated)
+
+- **`DeleteProgramMemberPolicy`** (`ProgramId`, `PrincipalType`, `PrincipalId`, `Policies[]`) — removes
+  the listed policies from the principal (a **selective** detach, not a full member removal). Gated:
+  preview with `--dry-run`, get explicit approval, re-run the **same argv with `--yes`** appended (see
+  SKILL.md's exit-10 protocol). Show the user exactly which policies will be stripped.
+
+## 6. Gotchas
+
+- **No Delete/Modify for the program itself** — only members (`DeleteProgramMemberPolicy`) are
+  removable via this API. Renaming/deleting a program isn't exposed.
+- **`CreateProgram` dates are `yyyy-MM-dd` strings** on input but come back as epoch ints in reads —
+  don't assume the same type round-trips.
+- **`ProjectId` on `CreateProgramProjects` is an array** of numeric ids; **`PrincipalId` on member ops
+  is a string**.
+- **`DescribePrograms` → `Data.Programs[]`** (paged) vs **`DescribeProgramProjects` → `Data[]`** (the
+  array is `Data` itself). Match `--select` accordingly.
+- **`Create…MemberPolicy` is additive, `Delete…` is selective** — neither replaces a principal's full
+  policy set; list the exact policies you intend to add/remove.

package/skills/coding/references/project.md

@@ -0,0 +1,150 @@
+# coding-project
+
+A curated playbook for the **项目 (04)** category — the 27 project actions.
+
+This is the **foundational category**: most other playbooks in `references/` (issues, code, CI, artifacts) need
+a `ProjectId` or `ProjectName` first — this file is how you resolve one.
+
+## 1. The three project identifiers
+
+- **`ProjectId`** (numeric) — the primary key for most write/read actions (modify, archive, members,
+  roles, credentials, labels-create, delete).
+- **`ProjectName`** (string) — the project's **`Name`** (the slug used in URLs, e.g. `demo-project`),
+  **not** its `DisplayName`. Used by name-based reads (`DescribeProjectByName`, announcements).
+- **`DisplayName`** (string) — the human-friendly label shown in the UI. Distinct from `Name`; never
+  pass it where `ProjectName` is expected.
+
+So `CreateCodingProject` takes **both** `Name` (the slug) and `DisplayName` (the label).
+
+## 2. Find / resolve a project
+
+```bash
+# by name → get the ProjectId (and everything else)
+coding call DescribeProjectByName --param ProjectName=demo-project \
+  --select 'Project.Id,Project.Name,Project.DisplayName,Project.Archived' --json
+
+# by id
+coding call DescribeOneProject --param ProjectId=341 --json
+
+# projects the current user has joined — UserId comes from whoami (SKILL.md / DescribeCodingCurrentUser)
+coding call DescribeUserProjects --param UserId=254 \
+  --select 'ProjectList[].Id,ProjectList[].Name,ProjectList[].DisplayName' --json
+
+# team-wide list (paged; optional ProjectName filter; QueryArchived to include archived)
+coding call DescribeCodingProjects --param PageNumber=1 --param PageSize=50 --param QueryArchived=false \
+  --select 'Data.ProjectList[].Id,Data.ProjectList[].Name,Data.ProjectList[].DisplayName' --json
+
+# projects exposing a given top-level menu/feature. MenuName is the menu LABEL as shown in the UI
+# (e.g. "项目协同"); labels vary by deployment, so verify the actual menu name before relying on it.
+coding call DescribeProjectsByFeature --param MenuName=项目协同 --json
+```
+
+## 3. Create, modify, archive
+
+```bash
+# Name = slug, DisplayName = label, ProjectTemplate ∈ CODE_HOST | PROJECT_MANAGE | DEV_OPS | DEMO_BEGIN,
+# Shared = 0 (private) | 1 (shared/open-source)
+coding call CreateCodingProject --data '{"Name":"new-svc","DisplayName":"New Service",
+  "Description":"…","ProjectTemplate":"DEV_OPS","Shared":0}' --json
+# richer template-based create. NOTE: Label here is an integration enum (TKE|TCB|SLS|QUICKSTART|APIGW),
+# NOT a free-form project label; Invisible hides the project from non-members.
+coding call CreateProjectWithTemplate --data '{"Name":"new-svc","DisplayName":"New Service",
+  "ProjectTemplate":"DEV_OPS","Shared":0,"Invisible":false,"Label":"QUICKSTART"}' --json
+
+# edit metadata (Name + DisplayName required even if unchanged; dates are "YYYY-MM-DD")
+coding call ModifyProject --param ProjectId=341 --param Name=demo-project --param DisplayName="Demo" --json
+
+# archive / unarchive (reversible; not a delete)
+coding call ModifyProjectArchive   --param ProjectId=341 --json
+coding call ModifyProjectUnarchive --param ProjectId=341 --json
+```
+
+## 4. Members & roles
+
+```bash
+# the project's role/usergroup definitions
+coding call DescribeProjectRoles --param ProjectId=341 --select 'Roles[].RoleId,Roles[].RoleTypeName' --json
+
+# member list — RoleId here ONLY filters the list to one role (it is NOT the add-member identifier; see below)
+coding call DescribeProjectMembers --param ProjectId=341 --param PageNumber=1 --param PageSize=50 --param RoleId=5 \
+  --select 'Data.ProjectMembers[].Id,Data.ProjectMembers[].Name,Data.ProjectMembers[].Email' --json
+
+# principals = members + user-groups + departments (Keyword to search)
+coding call DescribeProjectMemberPrincipals --param ProjectId=341 --param PageNumber=1 --param PageSize=50 --json
+
+# add principals: each is {PrincipalId(string), PrincipalType, PolicyIds:[int]} — pass via --data.
+# PrincipalId is a STRING ("254", not 254); PrincipalType "USER" (groups/depts use other values).
+# PolicyIds (权限组ID, the permission/role-group ids) is what grants the role — NOT the RoleId above.
+coding call CreateProjectMemberPrincipal --data '{"ProjectId":341,"Principals":[
+  {"PrincipalId":"254","PrincipalType":"USER","PolicyIds":[12]}]}' --json
+# DeleteProjectMemberPrincipal removes one — it is exit-10 gated (see §8)
+```
+
+## 5. Labels
+
+Two differently-purposed actions — don't confuse them:
+
+```bash
+# labels OF a project
+coding call DescribeAllProjectLabels --param ProjectId=341 --select 'Labels[].Id,Labels[].Name,Labels[].Color' --json
+# projects that HAVE a given label (cross-project lookup)
+coding call DescribeProjectLabels --param Label=backend --json
+
+coding call CreateProjectLabel --param ProjectId=341 --param Name=urgent --param Color="#FF0000" --json
+# edit needs LabelId (from DescribeAllProjectLabels) plus ProjectId + Name + Color (all required)
+coding call ModifyProjectLabel --param ProjectId=341 --param LabelId=88 --param Name=urgent --param Color="#FF8800" --json
+# DeleteProjectLabel is exit-10 gated (see §8)
+```
+
+## 6. Announcements
+
+```bash
+coding call DescribeProjectAnnouncements --param ProjectName=demo-project --param PageNumber=1 --param PageSize=20 \
+  --select 'List[].Id,List[].ContentOrigin' --json
+coding call CreateProjectAnnouncement --param ProjectName=demo-project --param Content="Maintenance tonight" --json
+# edit needs the announcement Id (from the list above) plus ProjectName + Content (all required)
+coding call ModifyProjectAnnouncement --param ProjectName=demo-project --param Id=12 --param Content="Rescheduled" --json
+# DeleteProjectAnnouncement is exit-10 gated (see §8)
+```
+
+## 7. Credentials
+
+```bash
+coding call DescribeProjectCredentials --param ProjectId=341 \
+  --select 'Data.CredentialList[].CredentialId,Data.CredentialList[].Name' --json
+```
+
+The list returns only `CredentialId` + `Name` per credential (no secret values, no type field). Treat
+credentials as **secrets**: refer to them by name for the user; never attempt to surface secret material.
+
+## 8. Destructive actions (exit-10 gated)
+
+`DeleteOneProject` (deletes the whole project), `DeleteProjectMemberPrincipal`, `DeleteProjectLabel`,
+`DeleteProjectAnnouncement`. Follow SKILL.md's protocol: preview with `--dry-run`, get explicit
+user approval, re-run the **same argv with `--yes`**.
+
+> **`DeleteOneProject` is irreversible and wipes everything in the project** (repos, issues, pipelines,
+> artifacts). To merely hide a project, use `ModifyProjectArchive` (§3) instead — it's reversible.
+> Resolve and double-check the `ProjectId` against the project's name before approving a delete.
+
+```bash
+coding call DeleteOneProject --param ProjectId=341 --dry-run --json   # show user
+coding call DeleteOneProject --param ProjectId=341 --yes --json        # only after explicit approval
+```
+
+## 9. Gotchas
+
+- **`ProjectName` is the slug (`Name`), not `DisplayName`.** Resolve once via `DescribeProjectByName` and
+  reuse the numeric `Id` for the many `ProjectId`-keyed actions.
+- **`DescribeUserProjects` needs a `UserId`** — get it from `coding auth status` / `DescribeCodingCurrentUser`
+  (the current user's `Id`), not from a project.
+- **Two label actions, opposite directions**: `DescribeAllProjectLabels` (labels *of* a project, by
+  `ProjectId`) vs `DescribeProjectLabels` (projects *with* a label, by `Label`).
+- **List wrappers vary**: `DescribeUserProjects`→ top-level `ProjectList[]`; `DescribeCodingProjects`→
+  `Data.ProjectList[]`; `DescribeProjectMembers`→ `Data.ProjectMembers[]`; `DescribeProjectAnnouncements`→
+  top-level `List[]`; `DescribeProjectRoles`→ `Roles[]`; `DescribeAllProjectLabels`→ `Labels[]`; but
+  `DescribeProjectLabels`→ `ProjectList[]` (it returns projects, not labels); `DescribeProjectCredentials`→
+  `Data.CredentialList[]`. Match `--select` accordingly.
+- **Archive ≠ delete.** `ModifyProjectArchive` is reversible; `DeleteOneProject` is not.
+- **Member/delete ops need project-admin scope** — that's what an exit-8 `UnauthorizedOperation` means
+  here (a scope gap, not a wrong token).

package/skills/coding/references/servicehook.md

@@ -0,0 +1,112 @@
+# coding-servicehook
+
+A curated playbook for the **Service Hook (06)** category — 10 actions that bind CODING events
+(issue/MR/CI/artifact/wiki/…) to an outbound notifier (chat robot or raw webhook).
+
+## 1. Identifiers & shape
+
+- **`ProjectId`** (int64) scopes almost every action. `TargetType` says what that id *means*:
+  `PROJECT` (default), `SPACE_NODE` (研发空间), or `PROGRAM` (项目集). For a plain project hook,
+  `ProjectId` = the numeric project id and `TargetType` = `PROJECT`. **`DescribeServiceHooks` (list)
+  and `EnabledServiceHook` require `TargetType`**; the other 06 actions treat it as optional (default
+  `PROJECT`).
+- **`Id`** is the hook id (a **string**). ⚠️ **It's an *array* on the batch verbs** (`DeleteServiceHook`,
+  `EnabledServiceHook`, `PingServiceHook` all take `Id: ["…"]`) but a **single string** on the
+  read/modify verbs (`DescribeServiceHook`, `DescribeServiceHookLogs`, `ModifyServiceHook`). Match the
+  shape per action or you'll get a validation/remote error.
+- **`ServiceHookLogId`** (the per-delivery log id, a string) is what `ResendServiceHookLog` keys off —
+  **not** `Id`/`ProjectId`. Get it from `DescribeServiceHookLogs` → `Data.Log[].Id`.
+
+> ⚠️ **Response wrapping is uneven** (match `--select` to each):
+> - create/modify/single-read → top-level **`ServiceHook`** (object), **not** under `Data`.
+> - list → **`Data.ServiceHook[]`**; logs → **`Data.Log[]`**; event catalog → top-level **`Event[]`**.
+> - enable/delete/ping → top-level **`Succeed`** (bool); resend → **`Data.Success`** (bool).
+
+## 2. Orient — events & existing hooks
+
+```bash
+# the event catalog you can subscribe to (Name = the value you put in Event[]; Label = its display
+#   name; GroupName/GroupLabel group the events)
+coding call DescribeEvents --select 'Event[].GroupLabel,Event[].GroupName,Event[].Label,Event[].Name' --json
+
+# list hooks in a project (TargetType + paging are required)
+coding call DescribeServiceHooks --data '{"ProjectId":450,"TargetType":"PROJECT","PageNumber":1,"PageSize":20}' \
+  --select 'Data.TotalCount,Data.ServiceHook[].Id,Data.ServiceHook[].Name,Data.ServiceHook[].Service,Data.ServiceHook[].Enabled,Data.ServiceHook[].Event' --json
+
+# read one hook (single Id, not an array)
+coding call DescribeServiceHook --param ProjectId=450 --param Id=<hook-id> \
+  --select 'ServiceHook.Id,ServiceHook.Name,ServiceHook.Event,ServiceHook.Action,ServiceHook.ActionProperties,ServiceHook.Enabled' --json
+```
+
+Event names are enum strings like `ISSUE_CREATED`, `GIT_MR_MERGED`, `CI_JOB_FINISHED`,
+`ARTIFACTS_VERSION_RELEASED`, `WIKI_UPDATED` (the full set is in `DescribeEvents` and `coding schema
+CreateServiceHook`). Subscribe to a list of them via `Event: [...]`.
+
+## 3. Create / modify a hook
+
+The two tricky params are JSON **strings** (escaped JSON inside the field), not nested objects:
+
+- **`ActionProperty`** — the notifier config: the robot/webhook URL (`service_url`) and message type.
+- **`FilterProperty`** — an optional event filter (e.g. only issues of a given type/priority).
+- **`Service`** ∈ `WebHook | WeCom | DingDing | FeiShu | Jenkins`; pick the matching **`ServiceAction`**:
+  `webhook_http_post`/`webhook_http_get`, `wecom_group_chat_robot`, `dingding_group_chat_robot`,
+  `feishu_group_chat_robot`, `jenkins_generic_build_job`.
+
+```bash
+# create — notify a WeCom group robot on issue creation
+coding call CreateServiceHook --data '{
+  "ProjectId":450,"TargetType":"PROJECT","Name":"issue→WeCom","Enabled":true,
+  "Service":"WeCom","ServiceAction":"wecom_group_chat_robot",
+  "Event":["ISSUE_CREATED"],
+  "ActionProperty":"{\"service_url\":\"https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…\",\"msg_type\":\"markdown\"}",
+  "FilterProperty":"{\"type\":\"MISSION\",\"priority\":\"1\"}"
+}' --select 'ServiceHook.Id,ServiceHook.Name,ServiceHook.Enabled' --json
+
+# modify — ⚠️ ModifyServiceHook requires Id + ALL of these resupplied: Event, Service, ServiceAction,
+#   ActionProperty, FilterProperty, Enabled (FilterProperty is REQUIRED here, unlike on create).
+#   Read the hook first so you don't drop fields you meant to keep.
+coding call ModifyServiceHook --data '{"ProjectId":450,"Id":"<hook-id>","Name":"issue→WeCom (v2)",
+  "Enabled":true,"Service":"WeCom","ServiceAction":"wecom_group_chat_robot","Event":["ISSUE_CREATED","ISSUE_STATUS_UPDATED"],
+  "ActionProperty":"{\"service_url\":\"…\",\"msg_type\":\"markdown\"}","FilterProperty":"{}"}' --json
+
+# just flip the on/off switch (batch; Id is an array)
+coding call EnabledServiceHook --data '{"ProjectId":450,"TargetType":"PROJECT","Id":["<hook-id>"],"Enabled":false}' --json
+```
+
+## 4. Test & debug deliveries
+
+```bash
+# fire a test delivery now (batch; Id is an array) → top-level Succeed
+coding call PingServiceHook --data '{"ProjectId":450,"Id":["<hook-id>"]}' --select 'Succeed' --json
+
+# paged delivery log for one hook (single Id). Status int + ResponseStatus tell you why it failed.
+coding call DescribeServiceHookLogs --data '{"ProjectId":450,"Id":"<hook-id>","PageNumber":1,"PageSize":20}' \
+  --select 'Data.TotalCount,Data.Log[].Id,Data.Log[].Event,Data.Log[].Status,Data.Log[].ResponseStatus,Data.Log[].SendAt' --json
+
+# resend ONE failed delivery — keyed by the log id (Data.Log[].Id above), not the hook id
+coding call ResendServiceHookLog --param ServiceHookLogId=<log-id> --select 'Data.Success' --json
+```
+
+## 5. Destructive action (exit-10 gated)
+
+- **`DeleteServiceHook`** (`ProjectId`, `Id: ["…"]` array, optional `TargetType`) — permanently removes
+  the hook(s). Gated: preview with `--dry-run`, get explicit approval, re-run the **same argv with
+  `--yes`** appended (see SKILL.md's exit-10 protocol). It deletes **every** id in the array, so
+  show the user the exact list first.
+
+## 6. Gotchas
+
+- **`Id` is array-vs-single by verb** — array on delete/enable/ping (batch), single on
+  read-one/logs/modify. Don't carry one shape across calls.
+- **`ActionProperty` / `FilterProperty` are escaped-JSON *strings***, not objects — `service_url` +
+  `msg_type` go inside `ActionProperty`. `FilterProperty` is **optional on `CreateServiceHook` but
+  required on `ModifyServiceHook`** (use `"{}"` for no filter).
+- **`ModifyServiceHook` requires every field resupplied** (Id, Event, Service, ServiceAction,
+  ActionProperty, FilterProperty, Enabled) — read the hook first (`DescribeServiceHook`) so you don't
+  drop a field you meant to keep.
+- **`ResendServiceHookLog` takes only `ServiceHookLogId`** — no `ProjectId`, no hook `Id`.
+- **`DescribeServiceHooks` requires `TargetType`** (and `PageNumber`/`PageSize`); the single-read and
+  most writes default `TargetType` to `PROJECT`.
+- **Uneven wrapping**: create/modify/single-read → top-level `ServiceHook`; list → `Data.ServiceHook[]`;
+  logs → `Data.Log[]`; events → top-level `Event[]`; enable/delete/ping → top-level `Succeed`; resend →
+  `Data.Success`.