@mu-cabin/coding-cli 0.1.0

package/skills/coding/references/code.md

@@ -0,0 +1,145 @@
+# coding-code
+
+A curated playbook for the **代码托管 (09)** category — the 152 Git/MR actions.
+
+## 1. Identifiers — get the DepotId first
+
+Almost every action keys off **`DepotId`** (a numeric repo id), *not* the repo name. `DepotPath` is an
+optional companion on most calls. So the universal first step is "resolve repo name → DepotId" (§2).
+
+- **`DepotId`** — numeric repository id, required by nearly all git/MR actions.
+- **`MergeId`** — the merge-request id; the key for every per-MR action (detail, diff, reviewers,
+  merge, close). MR list items carry both `Id` and `MergeId` — use **`MergeId`** for subsequent calls.
+- **`ReviewerGlobalKey`** — reviewers/mergers are addressed by **GlobalKey** (a string), not numeric id.
+- **Branches** are addressed by name; create needs a `StartPoint` (a branch name or commit sha).
+- **Files/commits** need a `Ref` (branch/tag/sha) and a `Path`.
+
+## 2. Resolve the repo → DepotId
+
+```bash
+# repos the current user can read (simplest, no ids needed)
+coding call DescribeMyDepots --param PageNumber=1 --param PageSize=50 \
+  --select 'Payload.Depots[].Id,Payload.Depots[].Name,Payload.Depots[].ProjectName,Payload.Depots[].DefaultBranch' --json
+
+# all repos in a project (needs the numeric ProjectId)
+coding call DescribeProjectDepotInfoList --param ProjectId=341 \
+  --select 'DepotData.Depots[].Id,DepotData.Depots[].Name,DepotData.Depots[].DefaultBranch' --json
+
+# by exact name (needs team GlobalKey + project + depot name)
+coding call DescribeDepotByNameInfo --param TeamGk=<team> --param ProjectName=demo --param DepotName=backend \
+  --select 'Depot.Id,Depot.DefaultBranch,Depot.HttpsUrl,Depot.SshUrl' --json
+```
+
+Cache the `DepotId` (and default branch) for the session.
+
+## 3. Browse code
+
+```bash
+# branches
+coding call DescribeGitBranches --param DepotId=123 --param PageSize=50 \
+  --select 'Branches[].BranchName,Branches[].IsDefaultBranch,Branches[].IsProtected,Branches[].Sha' --json
+
+# directory listing at a ref (Path defaults to repo root)
+coding call DescribeGitFiles --param DepotId=123 --param Ref=master --param Path=src \
+  --select 'Items[].Name,Items[].Path,Items[].Mode' --json
+
+# a file's content at a specific commit
+coding call DescribeGitFileContent --param DepotId=123 --param CommitSha=<sha> --param Path=src/app.ts --json
+
+# commit history on a ref (KeyWord / Path / date range filter the list)
+coding call DescribeGitCommitInfos --param DepotId=123 --param Ref=master --param PageSize=20 \
+  --select 'Commits[].Sha,Commits[].ShortMessage,Commits[].AuthorName,Commits[].CommitDate' --json
+coding call DescribeGitCommitDiff --param DepotId=123 --param Sha=<sha> --json   # one commit's diff (param is Sha)
+```
+
+## 4. Branches & tags
+
+```bash
+coding call CreateGitBranch --param DepotId=123 --param BranchName=feature/login --param StartPoint=master --json
+coding call DescribeGitTags --param DepotId=123 --json
+coding call CreateGitTag --data '{"DepotId":123,"TagName":"v1.2.0","StartPoint":"master","Message":"release"}' --json
+# DeleteGitBranch / DeleteGitTag / DeleteGitMergedBranches are gated — see §7
+```
+
+## 5. Merge requests — the lifecycle
+
+```bash
+# 5a. CREATE — two near-identical actions exist:
+#   CreateGitMergeReq    → also accepts inline `Reviewers` (comma-separated GlobalKeys)  ← prefer this
+#   CreateGitMergeRequest→ same minus Reviewers
+coding call CreateGitMergeReq --data '{
+  "DepotId":123, "SrcBranch":"feature/login", "DestBranch":"master",
+  "Title":"Add SMS login", "Content":"…", "Reviewers":"userA,userB"}' --json
+
+# 5b. LIST  (Status filter ∈ OPEN|CLOSE|ALL|ACCEPTED; plus KeyWord, Source/TargetBranches, Reviewer/Creator/Merger…)
+coding call DescribeDepotMergeRequests --param DepotId=123 --param Status=OPEN --param PageSize=20 \
+  --select 'Data.List[].MergeId,Data.List[].Title,Data.List[].Status,Data.List[].SourceBranch,Data.List[].TargetBranch' --json
+# also: DescribeSelfMergeRequests (mine), DescribeProjectMergeRequests (whole project)
+
+# 5c. DETAIL + diff + discussion
+coding call DescribeMergeReqInfo --param DepotId=123 --param MergeId=45 --json
+coding call DescribeGitMergeRequestDiffs --param DepotId=123 --param MergeId=45 --json         # changed-file list
+coding call DescribeGitMergeRequestDiffDetail --param DepotId=123 --param MergeId=45 --param Path=src/app.ts --json
+coding call DescribeSingeMergeRequestNotes --param DepotPath=team/demo/backend --param MergeId=45 --json   # comments (keys off DepotPath)
+
+# 5d. REVIEWERS
+coding call CreateMergeRequestReviewer --param DepotId=123 --param MergeId=45 --param ReviewerGlobalKey=userC --json
+coding call DescribeMergeRequestReviewers --param DepotId=123 --param MergeId=45 --json
+
+# 5e. COMMENT  (NOTE: this action keys off DepotPath, not DepotId; ParentId 0 = root.
+#     Omit `Form` for an MR-level comment; supply it for a diff-line comment.)
+coding call CreateMergeRequestNote --param DepotPath=team/demo/backend --param MergeId=45 \
+  --param ParentId=0 --param Content="LGTM" --json
+
+# 5f. CAN-MERGE check (uses branch names, not MergeId)
+coding call DescribeCanMerge --param DepotId=123 --param Source=feature/login --param Target=master --json
+
+# 5g. MERGE — all flags required. Squash/IsFastForward/IsDelSourceBranch are booleans; Message is the commit msg.
+coding call ModifyMergeMR --data '{"DepotId":123,"MergeId":45,"Message":"Merge !45",
+  "Squash":false,"IsFastForward":false,"IsDelSourceBranch":true}' --json
+
+# title/description edits, rebase, or close instead of merge:
+coding call ModifyGitMergeRequest --param DepotId=123 --param MergeId=45 --param Title="…" --json
+coding call ModifyGitMergeRequestRebase --param DepotId=123 --param MergeId=45 --json
+coding call ModifyCloseMR --param DepotId=123 --param MergeId=45 --json   # close without merging (not destructive-gated)
+```
+
+## 6. Writing files / commits, releases (less common)
+
+`CreateGitFiles` / `ModifyGitFiles` commit content directly — **both** require `Ref`, `Message`, and
+`LastCommitSha` (the current head sha, for optimistic-lock conflict detection). `CreateGitCommit` makes
+a multi-file commit (keys off `DepotPath`, not `DepotId`; also needs `LastCommitSha`).
+`CreateGitRelease` / `DescribeGitReleases` manage releases. Prefer normal git over the API for bulk
+content work; use these only when you must operate purely through the OpenAPI.
+
+## 7. Destructive actions (exit-10 gated)
+
+`DeleteGitDepot`, `DeleteGitBranch`, `DeleteGitMergedBranches`, `DeleteGitFiles`, `DeleteGitTag`,
+`DeleteGitRelease`, `DeleteGitDeployKey`, `DeleteMergeRequestReviewer`, `DeleteMergeRequestNote`,
+`DeleteBranchProtection`(+`Member`), `DeleteGitProtectedTagRule`, `DeleteSshKey`/`DeleteMemberSshKey`.
+(`ModifyGitDepotArchive` is **not** gated — indexed `write` — but archiving hides the repo; confirm
+anyway.) Follow SKILL.md's protocol: preview with `--dry-run`, get explicit
+user approval, then re-run the **same argv with `--yes`**. `DeleteGitMergedBranches` is bulk — it skips
+protected branches but still deletes every merged branch; confirm scope before approving.
+
+```bash
+coding call DeleteGitBranch --param DepotId=123 --param BranchName=feature/login --dry-run --json   # show user
+coding call DeleteGitBranch --param DepotId=123 --param BranchName=feature/login --yes --json         # after approval
+```
+
+> **Merging is not exit-10 gated** (`ModifyMergeMR` is classified `write`). Treat it as consequential
+> anyway: confirm the MR id, source/target, and the squash/delete-branch flags with the user before merging.
+
+## 8. Gotchas
+
+- **`DepotId` is the key, not the repo name** — always resolve it via §2 first. `DepotPath` is optional
+  on most calls, but a few use it **instead of** `DepotId`: `CreateMergeRequestNote`,
+  `DescribeSingeMergeRequestNotes`, and `CreateGitCommit` have **no `DepotId` param** (key off
+  `DepotPath`), and `DeleteGitMergedBranches` requires **both**. Check `coding schema` when unsure.
+- **Reviewers/mergers use `GlobalKey` (string), not numeric user id.**
+- **Two MR-create actions**: `CreateGitMergeReq` (supports inline `Reviewers`) and `CreateGitMergeRequest`.
+  Pick one; don't call both. The MR key for everything after is **`MergeId`** (not the list item's `Id`).
+- **`ModifyMergeMR` requires all four control fields** (`Message`, `Squash`, `IsFastForward`,
+  `IsDelSourceBranch`) — a missing required field is a validation error (exit 11).
+- Diffs and trees are large — `--select`/`--limit` aggressively, and prefer `DescribeGitMergeRequestDiffDetail`
+  for a single file over pulling the whole MR diff.

package/skills/coding/references/export.md

@@ -0,0 +1,42 @@
+# coding-export
+
+A curated playbook for the **导出任务 / Export jobs (17)** category — 3 actions implementing an async
+"export pages → ZIP of Markdown" pipeline. **No action here is destructive** (all are `write` risk; none
+trips the exit-10 gate) — but note these actions break the usual naming convention (verb is a *suffix*:
+`DocumentJob{Create,Start,Status}`).
+
+## 1. The export pipeline (create → start → poll)
+
+```bash
+# 1. create the job. Event is fixed; EventBody is an escaped-JSON STRING naming the subject.
+#    belongType ∈ project|team|program ; belongId is that subject's numeric id.
+coding call DocumentJobCreate --data '{"Event":"PAGE_EXPORT_TO_ZIP_MD",
+  "EventBody":"{\"belongType\":\"project\",\"belongId\":341}"}' --select 'JobId' --json
+# → top-level JobId (a string) — carry it through the next two calls
+
+# 2. start the job (it does not run on create)
+coding call DocumentJobStart --param JobId=<JobId> --json   # → only RequestId
+
+# 3. poll status until done; Result is a signed COS download URL (⚠️ valid ~30 min, then expires)
+coding call DocumentJobStatus --param JobId=<JobId> --select 'Status,ProcessRate,Result' --json
+```
+
+The three values that thread through: `DocumentJobCreate` yields the **`JobId`** (top-level); `…Start`
+kicks it off; `…Status` returns **`Status`** (string), **`ProcessRate`** (a progress object), and once
+finished **`Result`** — the signed download URL.
+
+> ⚠️ **`Result` is a time-limited COS link (~30 min per the spec).** Download promptly. The CLI does not
+> download the bytes — hand the `Result` URL to the user (or `curl` it out of band) before it expires.
+
+## 2. Notes
+
+- **Two separate steps to run a job**: `DocumentJobCreate` only *registers* the job; it does not run
+  until `DocumentJobStart`. Poll `DocumentJobStatus` after starting.
+- **`EventBody` is an escaped-JSON string**, not a nested object: `{"belongType":"…","belongId":…}`.
+  `belongType` is `project` | `team` | `program`; `belongId` is the matching numeric id (resolve a
+  project id via the `references/project.md` playbook, a program id via `references/program.md`).
+- **Responses are top-level**, not under `Data`: `JobId` (create), `Status`/`ProcessRate`/`Result`
+  (status). Match `--select` accordingly.
+- **`Event` is fixed** to `PAGE_EXPORT_TO_ZIP_MD` (the only documented export type).
+- **Export requires team/project admin scope** — that's what an exit-8 `UnauthorizedOperation` means
+  here (a scope gap, not a wrong token).

package/skills/coding/references/files.md

@@ -0,0 +1,66 @@
+# coding-files
+
+A curated playbook for the **文件网盘 / File disk (14)** category — 3 actions implementing an upload
+pipeline. **No action in this category is destructive** — there's no exit-10 gate here (and no
+delete/list/download action either).
+
+## 1. The upload pipeline (3 steps, like the Wiki ZIP flow)
+
+Uploading a file is **presign → upload bytes out-of-band → register**. The CLI does steps 1 and 3; the
+actual byte transfer (step 2) is a direct PUT to Tencent COS / MinIO that the CLI does **not** perform.
+
+```bash
+# 1. presign — get the upload URL + the keys you carry forward
+coding call DescribePreSignUploadUrl --data '{"ProjectName":"demo","FileName":"report.csv",
+  "ContentType":"text/csv","FolderType":0,"FolderId":0}' \
+  --select 'Data.UploadLink,Data.StorageKey,Data.AuthToken,Data.Headers' --json
+
+# 2. PUT the bytes to Data.UploadLink — OUT OF BAND (curl/SDK). Use Data.Headers (a JSON string of
+#    x-cos-security-token etc.) and the signed Authorization embedded in UploadLink. The CLI does not
+#    move bytes; this step happens in the user's shell.
+
+# 3. register the uploaded object as a CODING file — carries StorageKey + AuthToken from step 1
+coding call CreateFile --data '{"StorageKey":"<from step 1>","AuthToken":"<from step 1>"}' \
+  --select 'Data.Id,Data.Name' --json   # → Data.Id is the file id
+```
+
+The values that thread through: step 1 yields **`StorageKey`** (the stored object path), **`AuthToken`**
+(identity proof for step 3), **`UploadLink`** (the signed PUT URL), and **`Headers`** (a JSON *string*
+of upload headers). Step 3 (`CreateFile`) needs only `StorageKey` + `AuthToken` and returns the new
+file's `Data.Id`.
+
+## 2. ⚠️ `FolderType` picks the destination — get it right
+
+`DescribePreSignUploadUrl` has two distinct use cases controlled by **`FolderType`**:
+
+| Goal | `FolderType` | `FolderId` |
+|---|---|---|
+| Upload to the **file disk (网盘)** | `0` (常规文件夹) | a real folder id from `CreateFolder` (or `0` for root) |
+| Upload an **issue/项目协同 attachment** | `1` (隐藏文件夹) | `0` (not needed) |
+
+For the attachment case: get the `Data.Id` from `CreateFile`, then pass it into an issue create/modify
+as `FileIds:[<id>]` (that lives in the `references/issues.md` playbook, action `CreateIssue`/`ModifyIssue`).
+
+## 3. Folders (file disk only)
+
+```bash
+# create a folder in the file disk. ParentId 0 = root. Returns Data.Id (use as FolderId in step 1).
+coding call CreateFolder --data '{"ProjectName":"demo","FoldName":"个人资料","ParentId":0}' \
+  --select 'Data.Id,Data.Name' --json
+```
+
+Note the param is **`FoldName`** (not `FolderName`) and **`ParentId`** (not `ParentFolderId`).
+
+## 4. Gotchas
+
+- **The byte upload (step 2) is out of band** — the CLI presigns and registers but does not PUT the
+  file. Hand the user the `UploadLink` + `Headers` to upload (COS/MinIO PUT), then run `CreateFile`.
+- **`FolderType`: `0` = file disk, `1` = issue attachment** (hidden folder). Picking the wrong one puts
+  the file in the wrong place. The `ContentType` should match what a browser would send (e.g.
+  `image/png`, `text/csv`).
+- **`CreateFile` keys off `StorageKey` + `AuthToken`** from the presign step — no `ProjectName` on this
+  call. It returns `Data.Id` (int) — the handle you feed into `FileIds[]` when attaching to an issue.
+- **Param spelling**: `CreateFolder` uses **`FoldName`** and **`ParentId`**; presign uses **`FolderId`**
+  (singular) + **`FolderType`**. Everything in this category wraps under **`Data`**.
+- **No delete / list / download** here — this category only presigns, registers files, and creates
+  folders. For attachment-to-issue wiring, see the `references/issues.md` playbook.

package/skills/coding/references/issues.md

@@ -0,0 +1,175 @@
+# coding-issues
+
+A curated playbook for the **项目协同 (08)** category — the 65 issue/iteration actions.
+
+## 1. Concepts & identifiers (resolve these before mutating)
+
+- **ProjectName** — the project's name/identifier (the slug used in URLs, e.g. `demo-project`), **not**
+  its display label. Required by almost every action. If you only know the team or the display name,
+  list/resolve projects first (SKILL.md / `DescribeUserProjects` / `DescribeProjectByName`).
+- **IssueCode** — the per-project issue number the user sees (e.g. `#42` → `42`). The key for
+  read/modify/delete of a single issue. **Not** the same as the global issue id.
+- **Type** (the enum) vs **IssueTypeId** (a number):
+  - `Type` ∈ `REQUIREMENT` 需求 · `DEFECT` 缺陷 · `MISSION` 任务 · `EPIC` 史诗 · `SUB_TASK` 子任务 (for
+    `CreateIssue`). **List queries** (`DescribeIssueList`/`DescribeIssueListWithPage`) take an `IssueType`
+    of only `ALL`/`DEFECT`/`REQUIREMENT`/`MISSION`/`EPIC` — **no `SUB_TASK`**; reach sub-tasks via
+    `DescribeSubIssueList` on the parent.
+  - `IssueTypeId` is the numeric id of a *configured* type in this project (a project may have
+    several custom requirement/defect types). Get it from `DescribeProjectIssueTypeList`. `CreateIssue`
+    needs `Type`; `IssueTypeId` is only needed when the project has multiple types for that `Type`.
+- **Priority** is a **string code**, not a label: `"0"`低 · `"1"`中 · `"2"`高 · `"3"`紧急.
+- **StatusId** — status is an id, resolved per (project, IssueType) via `DescribeProjectIssueStatusList`.
+  You **transition** an issue by setting `StatusId` on `ModifyIssue`; there is no separate transition action.
+- **Dates** are `"YYYY-MM-DD"` strings (`StartDate`/`DueDate`).
+
+## 2. Orient — the one-time lookups
+
+```bash
+# what issue types exist in this project (gives Type + IssueTypeId + names)
+coding call DescribeProjectIssueTypeList --param ProjectName=demo \
+  --select 'IssueTypes[].IssueType,IssueTypes[].Id,IssueTypes[].Name' --json
+
+# the status pipeline for a given type (gives IssueStatusId you'll set on ModifyIssue)
+coding call DescribeProjectIssueStatusList --param ProjectName=demo --param IssueType=REQUIREMENT \
+  --select 'ProjectIssueStatusList[].IssueStatusId,ProjectIssueStatusList[].IssueStatus.Name' --json
+```
+
+Cache these for the session so you don't re-fetch them per issue.
+
+## 3. Find issues
+
+```bash
+# the user's own to-dos across the team (no ProjectName needed)
+coding call DescribeWorkbenchIssueList --param Type=REQUIREMENT --param PageSize=20 \
+  --select 'Data.IssueList[].Code,Data.IssueList[].Name,Data.IssueList[].Priority' --limit 20 --json
+
+# filtered list within a project — IssueType required; filter with Conditions
+coding call DescribeIssueList --data '{
+  "ProjectName":"demo", "IssueType":"ALL", "Offset":0, "Limit":20,
+  "SortKey":"UPDATED_AT", "SortValue":"DESC",
+  "Conditions":[
+    {"Key":"STATUS_TYPE","Value":"TODO,PROCESSING"},
+    {"Key":"ASSIGNEE","Value":"254"},
+    {"Key":"KEYWORD","Value":"login"}
+  ]
+}' --select 'IssueList[].Code,IssueList[].Name,IssueList[].Priority,IssueList[].IssueStatusName' --json
+```
+
+**Condition keys** (`Key`, with comma-separated `Value` for multi-select): `STATUS`, `STATUS_TYPE`
+(`TODO`/`PROCESSING`/`COMPLETED`), `ASSIGNEE`/`CREATOR`/`WATCHER` (user ids), `PRIORITY` (`0`–`3`),
+`LABEL`, `MODULE`, `ITERATION`, `KEYWORD` (name/code fuzzy), `ISSUE_TYPE`, `CREATED_AT`/`UPDATED_AT`/
+`DUE_DATE`/`START_DATE` (range `"2020-08-01_2020-08-31"`), `WORKING_HOURS` (range `"0.1_5.0"`),
+`CUSTOM` (also set `CustomFieldId`). Use `ConstValue:"UNSPECIFIC"` to match "unassigned/unset".
+For paged results with totals use `DescribeIssueListWithPage`.
+
+## 4. Create an issue
+
+```bash
+coding call CreateIssue --data '{
+  "ProjectName":"demo", "Type":"REQUIREMENT", "Name":"用户登录支持短信验证码",
+  "Priority":"2", "Description":"...", "AssigneeId":254,
+  "IterationCode":1001, "DueDate":"2026-06-01"
+}' --json
+```
+
+- `Name`, `Type`, `Priority`, `ProjectName` are the only required fields.
+- `SUB_TASK` **requires** `ParentCode`; `EPIC`/`SUB_TASK` ignore `IterationCode`/`EpicCode`.
+- Set `IssueTypeId` only if the project has multiple configured types for that `Type` (from §2).
+- Defaults to the type's initial status; pass an optional `StatusId` (resolved in §2) to create it
+  in a specific status, or transition afterward via `ModifyIssue` (§6).
+
+## 5. Read one issue
+
+```bash
+coding call DescribeIssue --param ProjectName=demo --param IssueCode=42 --json
+coding call DescribeIssueCommentList --param ProjectName=demo --param IssueCode=42 \
+  --select 'CommentList[].CommentId,CommentList[].Content,CommentList[].CreatorId' --json
+# activity log — ActionType + Target are BOTH required and combine (e.g. UPDATE+STATUS = status changes,
+# UPDATE+ASSIGNEE = reassignments, CREATE+SELF = creation). Or use DescribeIssueStatusChangeLogList.
+coding call DescribeIssueLogList --param ProjectName=demo --param IssueCode=42 \
+  --param ActionType=UPDATE --param Target=STATUS --json
+coding call DescribeSubIssueList --param ProjectName=demo --param IssueCode=42 --json              # children
+```
+
+## 6. Update — fields, assignee, status, iteration
+
+`ModifyIssue` is the single write path; pass `ProjectName` + `IssueCode` plus only the fields you change.
+
+```bash
+# transition status: resolve StatusId from §2, then set it
+coding call ModifyIssue --param ProjectName=demo --param IssueCode=42 --param StatusId=44318126 --json
+
+# reassign + bump priority
+coding call ModifyIssue --param ProjectName=demo --param IssueCode=42 \
+  --param AssigneeId=254 --param Priority=3 --json
+
+# move into / out of an iteration
+coding call ModifyIssue --param ProjectName=demo --param IssueCode=42 --param IterationCode=1001 --json
+```
+
+- Description has its own action: `ModifyIssueDescription` (long rich text).
+- Labels/watchers/releases use add+`Del…`/`Update…` list params (e.g. `LabelIds` to add, `DelLabelIds`
+  to remove) — check `coding schema ModifyIssue` for the exact field.
+- Use `--dry-run` first when the user wants to see the change before it lands.
+
+## 7. Comment & log work hours
+
+```bash
+# top-level comment: ParentId is required — use 0 for a root comment, or a comment Id to reply
+coding call CreateIssueComment --param ProjectName=demo --param IssueCode=42 \
+  --param ParentId=0 --param Content="Reviewed, looks good." --json
+
+# log work hours (StartAt is an epoch-ms timestamp; hours are floats)
+coding call CreateIssueWorkHours --data '{
+  "ProjectName":"demo","IssueCode":42,"SpendHour":3.5,"RemainingHour":1.0,
+  "StartAt":1716249600000,"WorkingDesc":"实现短信发送"}' --json
+coding call DescribeIssueWorkLogList --param ProjectName=demo --param IssueCode=42 --json
+```
+
+## 8. Iterations (sprints) & releases
+
+```bash
+coding call DescribeIterationList --param ProjectName=demo \
+  --select 'Data.List[].Code,Data.List[].Name,Data.List[].Status' --json
+coding call CreateIteration --data '{"ProjectName":"demo","Name":"Sprint 12",
+  "StartAt":"2026-05-25","EndAt":"2026-06-07","Goal":"登录改版"}' --json
+
+# batch-plan issues into an iteration
+coding call PlanIterationIssue --data '{"ProjectName":"demo","IterationCode":1001,
+  "IssueCode":[42,43,44]}' --json
+
+# start / complete / reopen a sprint — Operator ∈ start|complete|restart
+coding call ModifyIterationStatus --param ProjectName=demo --param IterationCode=1001 \
+  --param Operator=start --param StartAt=2026-05-25 --json
+# completing requires EndAt; JoinIterationCode optionally carries unfinished issues into another sprint
+coding call ModifyIterationStatus --param ProjectName=demo --param IterationCode=1001 \
+  --param Operator=complete --param EndAt=2026-06-07 --json
+```
+
+Releases (版本) mirror this: `DescribeReleaseList` / `CreateRelease` / `ModifyRelease`, and
+`DescribeReleaseIssueList` for a release's scope.
+
+## 9. Destructive actions
+
+`DeleteIssue`, `DeleteIteration`, `DeleteRelease`, `DeleteIssueWorkHours`, `DeleteIssueModule`,
+`DeleteIssueBlock`, `DeleteRequirementDefectRelation` are **gated (exit 10)**. (Comments have no
+delete action — only `CreateIssueComment`/`ModifyIssueComment`.)
+Follow SKILL.md's confirmation protocol: preview with `--dry-run`, get explicit user approval,
+then re-run the same argv with `--yes`. Resolve the exact `IssueCode`/`IterationCode` first — deletes
+are not reversible.
+
+```bash
+coding call DeleteIssue --param ProjectName=demo --param IssueCode=42 --dry-run --json   # show the user
+coding call DeleteIssue --param ProjectName=demo --param IssueCode=42 --yes --json        # after approval
+```
+
+## 10. Gotchas
+
+- **IssueCode is project-scoped**, not global — always pair it with `ProjectName`.
+- **Priority is `"0"`–`"3"`**, never the Chinese label. **Status is an id**, resolved per type (§2).
+- **Type vs IssueType vs IssueTypeId**: `CreateIssue` takes `Type` (the enum); **list queries take
+  `IssueType`** (same enum, different param name — there is no `Type` param on `DescribeIssueList`/
+  `DescribeIssueListWithPage`). Add the numeric `IssueTypeId` only when a project defines multiple
+  configured types for that enum.
+- `CreateIssueComment.ParentId` is **required** (`0` = root). `CreateIssueWorkHours.StartAt` is **epoch ms**.
+- Large boards: always `--select` the few fields you need and `--limit` arrays — issue payloads are huge.

package/skills/coding/references/org.md

@@ -0,0 +1,115 @@
+# coding-org
+
+A curated playbook for the **组织和成员 (02)** category — the 16 actions covering **team members** and
+the **department tree**.
+
+## 1. Two id systems — don't cross them
+
+| Context | Input id | Notes |
+|---|---|---|
+| **Team member** (team-level ops) | **`UserId`** (uint64) | what Delete/Lock/Unlock/DescribeTeamMember take. In *responses* the same value is the member's `Id`. `Name`/`GlobalKey`/`Email` are **not** input ids (except `DescribeTeamMemberByEmail`). |
+| **Department member** (membership/assignee ops) | **`RefId`** / **`RefIds[]`** | a *different* integer (部门用户 refId), obtained from `DescribeDepartmentMembers.Data.DepartmentMembers[].RefId`. **Not** the UserId. |
+
+**Member `Status` enum** (everywhere): `0` 不活跃 · `1` 活跃 · `-1` 被锁定 · `-2` 锁定登录 · `-3` 退出团队.
+
+## 2. Team members
+
+```bash
+# list team members (paginated). ShowDepartment=true attaches each member's department membership.
+coding call DescribeTeamMembers --param PageNumber=1 --param PageSize=50 \
+  --select 'Data.TeamMembers[].Id,Data.TeamMembers[].Name,Data.TeamMembers[].Email,Data.TeamMembers[].GlobalKey,Data.TeamMembers[].Status' --json
+
+# admins only (leaner shape — Id/Name/GlobalKey, NO Email/Status/Roles)
+coding call DescribeTeamAdminMembers --param PageNumber=1 --param PageSize=50 --select 'Data.Members[].Id,Data.Members[].Name,Data.Members[].GlobalKey' --json
+
+# look up one member — by UserId, or by email. Both return a single object at `TeamMember` (not under Data).
+coding call DescribeTeamMember --param UserId=254 --param ShowDepartment=true --select 'TeamMember.Id,TeamMember.Name,TeamMember.Email,TeamMember.Status,TeamMember.Roles' --json
+coding call DescribeTeamMemberByEmail --param Email=alice@example.com --select 'TeamMember.Id,TeamMember.Name,TeamMember.GlobalKey' --json
+```
+
+Lock / unlock are **two separate actions** (there is no lock flag), both keyed by `UserId`:
+
+```bash
+coding call ModifyTeamMemberLocked   --param UserId=254 --json   # returns only RequestId; re-read via DescribeTeamMember to confirm Status -1
+coding call ModifyTeamMemberUnlocked --param UserId=254 --json
+```
+
+## 3. Departments — the org tree
+
+The tree is expressed via `ParentId` (a parent department's id; **`0` = top level**). Mind that the
+department-id param name **changes per action** (see the table in §5).
+
+```bash
+# read the tree from a node down. GetTree=true returns the recursive subtree. Result at `DepartmentTree`.
+coding call DescribeDepartment --param DepartmentId=4001 --param GetTree=true \
+  --select 'DepartmentTree.Id,DepartmentTree.Name,DepartmentTree.Children' --json
+
+# create a department (ParentId=0 for a top-level one). → Department.Id
+coding call CreateDepartment --data '{"Name":"Platform","ParentId":0}' --json
+
+# modify — ⚠️ the dept's own id is `Id` here (not DepartmentId); Name + ParentId are also required.
+#   Changing ParentId MOVES the department under a new parent.
+coding call ModifyDepartment --data '{"Id":4002,"Name":"Platform Eng","ParentId":4001}' --json
+```
+
+## 4. Department members & assignees (负责人)
+
+Both consume **`RefIds` (an array)** — refIds, not UserIds. Get refIds from `DescribeDepartmentMembers`.
+
+```bash
+# list a department's members (paginated). Pointer=true → only DIRECT members (exclude sub-departments).
+coding call DescribeDepartmentMembers --param DepartmentId=4001 --param PageNumber=1 --param PageSize=50 \
+  --select 'Data.DepartmentMembers[].RefId,Data.DepartmentMembers[].UserId,Data.DepartmentMembers[].Name,Data.DepartmentMembers[].UserStatus' --json
+
+# add members to departments — DepartmentIds AND RefIds are BOTH arrays (members ↔ departments)
+coding call ModifyDepartmentMember --data '{"DepartmentIds":[4001],"RefIds":[5501,5502]}' --json
+
+# set a department's head(s) — DepartmentId is a SINGLE id here; RefIds is still an array
+coding call ModifyDepartmentAssignee --data '{"DepartmentId":4001,"RefIds":[5501]}' --json
+```
+
+`ModifyDepartmentMember` (which **departments a member belongs to**, plural `DepartmentIds`) vs
+`ModifyDepartmentAssignee` (who **leads one department**, single `DepartmentId`; surfaces as
+`Assignee:true` in a member's `Refs[]`). Different shapes — don't swap them.
+
+## 5. Third-party (LDAP) sync
+
+```bash
+# fire-and-forget sync of third-party department members (currently LDAP). No params. Rate-limited to
+# at most once per 2 minutes — don't loop on it.
+coding call TriggerDepartmentSync --json
+# poll status separately (no params; returns an opaque `Result`)
+coding call DescribeDepartmentSyncStatus --select 'Result' --json
+```
+
+## 6. Destructive actions (exit-10 gated)
+
+Two actions need `--yes` (preview with `--dry-run`, get explicit approval, re-run the **same argv with
+`--yes`** — see SKILL.md's exit-10 protocol):
+
+- **`DeleteTeamMember`** (`UserId`) — removes the member from the team.
+- **`DeleteDepartment`** (`DepartmentId`) — deletes a department node.
+
+## 7. Department-id param name cheat-sheet (the #1 trap)
+
+| Action | Dept id param | Shape |
+|---|---|---|
+| `CreateDepartment` | `ParentId` (parent) | scalar |
+| `ModifyDepartment` | **`Id`** (self) + `ParentId` (parent) | scalar |
+| `DeleteDepartment` / `DescribeDepartment` / `DescribeDepartmentMembers` / `ModifyDepartmentAssignee` | `DepartmentId` | scalar |
+| `ModifyDepartmentMember` | **`DepartmentIds`** | **array** |
+
+## 8. Gotchas
+
+- **`UserId` (team ops) vs `RefId` (department member/assignee ops)** are different integers — never
+  interchange them. Read a member's `RefId` from `DescribeDepartmentMembers`.
+- **Dept-id param name varies** (§7); **`RefIds` and (for ModifyDepartmentMember) `DepartmentIds` are
+  arrays** even for a single value.
+- **Lock/unlock are distinct actions**, no flag.
+- **Result wrapping**: paginated lists → `Data.<X>[]` (`Data.TeamMembers`, `Data.Members`,
+  `Data.DepartmentMembers`); single member reads → `TeamMember`; the tree → `DepartmentTree`; sync status
+  → `Result`. Match `--select` accordingly.
+- **`TriggerDepartmentSync` is rate-limited (≤1 / 2 min)** and returns nothing useful beyond `RequestId`
+  — poll `DescribeDepartmentSyncStatus`, don't re-trigger in a loop.
+- **Team/department administration needs an org-admin-scoped token** — that's what an exit-8
+  `UnauthorizedOperation` is telling you here (a scope gap, not a wrong token).