@yigemo/portal 0.2.4 → 0.2.8

package/README.md

@@ -107,18 +107,89 @@ ygmp zhixu auth status --json
 ygmp zhixu catalog --json
 ygmp zhixu organizations list --json
 ygmp zhixu organizations service ORGANIZATION_UUID --json
+ygmp zhixu organizations lifecycle plan ORGANIZATION_UUID --json
+ygmp zhixu organizations lifecycle notices ORGANIZATION_UUID --limit 20 --json
 ygmp zhixu organizations export ORGANIZATION_UUID --output organization.json
 ygmp zhixu orders list --organization ORGANIZATION_UUID --json
 ygmp zhixu orders list --organization ORGANIZATION_UUID --before NEXT_CURSOR --json
 ygmp zhixu orders get ORDER_UUID --json
 ```
 
+The current organization owner can prepare an acknowledgement with
+`ygmp zhixu operations prepare --organization ORGANIZATION_UUID --action acknowledge_data_lifecycle_notice --target NOTICE_UUID --file acknowledgement.json --idempotency-key ORIGINAL_KEY`,
+where `acknowledgement.json` contains `{}`. Inspect the preview and keep the
+operation reference for confirmation and recovery.
+
 To develop locally, use `--env local --zhixu-api-base-url http://127.0.0.1:3010`
 and the local Accounts issuer. `YGMP_ZHIXU_ACCESS_TOKEN` may supply a Zhixu
 session for that configured origin; tokens are never command-line flags.
 Exports create a private file and never overwrite an existing path. Reads
 and exports remain subject to enterprise permissions and retention.
 
+### Saved Zhixu accounts
+
+Save separate Accounts-authorized sessions and give them local names:
+
+```bash
+ygmp --env prod zhixu login --account personal
+ygmp --env prod zhixu login --account work
+ygmp --env prod zhixu auth list --json
+ygmp --env prod zhixu auth use personal --json
+ygmp --env prod zhixu --account work me --json
+ygmp --env prod zhixu --account work banks list --personal --json
+ygmp --env prod zhixu --account work auth refresh --json
+ygmp --env prod zhixu --account work logout --json
+```
+
+Successful login selects the saved account. Without a name, the first login
+generates one; subsequent unnamed logins reauthorize the current default and
+refuse a different browser identity. Reauthorizing the same user under a new
+name reuses the existing account and reports its existing name. Names must
+start with a letter or number and contain 1–64 ASCII letters, numbers, dots,
+underscores or hyphens. The name never grants permissions.
+
+`auth use` verifies the target identity online before changing the default;
+valid sessions need no browser login. A failed switch preserves the previous
+default. `--account` selects an account for only that command; it also works
+after nested subcommands. Scripts should specify it on every step. A running
+command keeps its original account even if another terminal changes the default.
+The personal or organization target remains explicit and independent.
+
+Saved sessions and defaults are isolated by application, environment, issuer,
+OAuth client and API origin. `YGMP_ZHIXU_ACCESS_TOKEN` retains its existing
+priority for commands without an account name. Combining it with `--account`
+fails before business requests. Unset it before login, `auth use` or refresh.
+`auth status` separates the saved default from the effective credential source;
+environment identity is unverified until read through `me`. Lists/status show
+cached metadata, not a guarantee of current server authorization. Scoped
+management writes report the selected identity on stderr, keeping stdout JSON
+compatible.
+
+`logout` revokes and forgets only the selected account. Removing the default
+clears the selection; it never selects a different account automatically.
+An unconfirmed revocation retains the account for an explicit logout retry.
+`logout --local-only` forgets local credentials without claiming server
+revocation. Unnamed logout still reports `environmentTokenStillSet` when an
+environment credential remains. Accounts browser sessions and other apps remain
+independent; issued access tokens follow the server's existing expiry policy.
+
+The private `~/.yigemo/portal/accounts-v3.json` file stores Zhixu sessions.
+Matching legacy `tokens.json` sessions migrate after identity verification;
+other application entries are preserved. End older CLI processes before the
+first migration, and do not share a refresh family between old/new binaries.
+After migration, the CLI never reimports a legacy entry for this app. Downgrades
+may require a fresh login; do not restore an already rotated refresh token.
+These are plaintext credential files protected by owner checks, private modes
+and atomic writes. No password or Accounts ID token is persisted.
+
+Cross-process locks serialize refresh, logout and file changes. An interrupted
+or uncertain rotation requires login instead of retrying the old refresh token.
+If a process dies with a lock, the CLI reports `AUTH_LOCK_OWNER_EXITED` and the
+specific lock path. Confirm its owner has exited and no older CLI is running
+before removing only that lock file, then retry. Live locks are never reclaimed
+on a timer. Chapterly/admin retain their existing authentication behavior;
+their multi-account commands and Travel handoff storage are outside this feature.
+
 Purchases and human service requests default to a dry-run. Use the current
 catalog item's SKU and its own `version`, exactly one recipient, and a stable
 idempotency key. Reuse that key when retrying the same operation.
@@ -191,6 +262,385 @@ The browser entry is `/app?view=subjective`. Personal Accounts sessions are
 required; enterprise workspaces and API/MCP credentials are not enabled for this
 workflow. These commands require a server release containing APIS-91.
 
+## Zhixu capability discovery and original operations
+
+Canonical self reads use the same owning service as MCP and the built-in
+assistant. Select the workspace context explicitly; it grants no organization
+membership or business access:
+
+```bash
+ygmp zhixu profile get --personal --json
+ygmp zhixu preferences get --personal --json
+ygmp zhixu connections setup --personal --json
+ygmp zhixu organizations memberships --organization <organization-id> --json
+ygmp zhixu organizations creation-entitlement --personal --json
+ygmp zhixu subjective ai-capabilities --personal --json
+```
+
+Membership and creation reads require explicit `organizations:read` and
+`organizations:create` machine scopes. Membership results contain only minimal
+own active metadata within the current credential or immutable task space;
+OAuth also intersects its current organization grants. Setup returns guidance,
+never a credential or a new grant. Existing `organizations list` keeps its
+legacy wire fields.
+
+The subjective AI snapshot requires explicit `subjective:read` for a machine
+credential and a personal workspace. PAT issuance still requires an explicit
+typed subjective bank range; this read does not grant access to answers. It
+reports current rollout and the existing explain quota without issuing quota,
+reserving usage or calling a model. Review writes remain separately gated.
+
+Connection metadata reads require `connections:read` and keep the exact
+selected connection separate from pagination:
+
+```bash
+ygmp zhixu connections list --personal --json
+ygmp zhixu connections get <connection-id> --personal --json
+ygmp zhixu connections audit <connection-id> --personal --limit 20 --json
+```
+
+OAuth can read only its current connection. The API and CLI verify the echoed
+connection selector; the built-in executor retains it in the original step
+hash and recovery input. Audit reads re-project historical rows and exclude
+credentials and raw request/model bodies. These reads do not issue credentials,
+change consent or grant access to the resources named in a connection.
+
+These require the matching Agent contract API. They validate the bundled wire
+contract and perform a logical read without write flags or an operation key.
+The existing `me` command and login/session probes keep their legacy endpoint
+so an API contract upgrade does not interfere with credential recovery.
+
+`capabilities contract` reads the contract bundled with this CLI offline.
+`capabilities summary` reads the live public feature and rollout summary without
+signing in. `capabilities list/get` evaluates the current customer identity and selected
+workspace through the API. A catalog entry or visible tool does not grant access.
+The original-operation commands require an API version with the same contract
+digest; a mismatch stops preparation and execution. They are implemented in
+source and local acceptance, and are not yet available on production.
+
+```bash
+ygmp zhixu capabilities contract --json
+ygmp zhixu capabilities summary --json
+ygmp zhixu capabilities list --personal --limit 20 --json
+ygmp zhixu capabilities get update_bank --personal --target BANK_UUID --json
+ygmp zhixu operations prepare --personal --action update_bank --target BANK_UUID --file bank-update.json --idempotency-key reviewed-update-1 --json
+ygmp zhixu operations get OPERATION_UUID --personal --json
+ygmp zhixu operations preview OPERATION_UUID --personal --json
+ygmp zhixu operations execute OPERATION_UUID --personal --execute --confirmation-token TOKEN --json
+ygmp zhixu operations wait OPERATION_UUID --personal --wait-timeout 30000 --json
+```
+
+For example, `bank-update.json` contains `{"description":"Reviewed description"}`.
+Preparation stores a reference and returns a preview without changing the bank.
+Preserve `operation.operationRef.id`. Execution defaults to preview; a business
+write requires `--execute` and the matching transient confirmation token. Use
+`--execute --yes` only when the user has explicitly authorized that same change;
+it obtains a fresh preview before execution. Production preparation and execution
+also require `--allow-prod-write`.
+
+For AI study actions, prepare `explain_attempt` against the original personal
+attempt with an empty JSON object. Prepare `analyze_mistakes` against one
+personal bank with `{"windowDays":7}` or `{"windowDays":30}`. Both previews
+show one unit of the applicable AI allowance and the maximum provider cost.
+If the provider receipt is pending, preserve the operation ID and use
+`operations get` or `operations wait` to check the same operation.
+
+```bash
+ygmp zhixu operations prepare --personal --action explain_attempt --target ATTEMPT_UUID --file empty.json --idempotency-key explanation-1 --json
+ygmp zhixu operations prepare --personal --action analyze_mistakes --target BANK_UUID --file analysis-window.json --idempotency-key analysis-1 --json
+```
+
+To request a platform AI review, use `review_subjective_with_ai` with an
+empty JSON object and the exact ID of your submitted subjective answer.
+The platform reads the original answer and rubric and saves one review.
+If a review already exists, the preview shows zero cost and allowance.
+
+```bash
+ygmp zhixu operations prepare --personal --action review_subjective_with_ai --target ATTEMPT_UUID --file empty.json --idempotency-key subjective-ai-review-1 --json
+```
+
+To prepare an export, put `{"components":["banks"]}` in `export.json`. Add
+`bankIds` to select specific banks, or use `--organization ORGANIZATION_UUID`
+in place of `--personal`. Review the data categories and bank count before
+executing with the preview's token.
+
+```bash
+ygmp zhixu operations prepare --personal --action create_data_export --file export.json --idempotency-key export-1 --json
+ygmp zhixu operations execute OPERATION_UUID --personal --execute --confirmation-token TOKEN --json
+ygmp zhixu transfers exports get JOB_UUID --personal --json
+```
+
+Use `receipt.result.id` as the job UUID. If the execute response is unavailable,
+read the original operation for its job UUID. The job continues in the transfer
+worker using the authorized selection from the confirmed preview.
+
+Prepare an import with `create_data_import`. The payload accepts either a
+supported manifest object or an authorized ready export's `exportJobId` and
+`manifestHash`. The completed receipt contains `receipt.result.job.id`.
+
+```bash
+ygmp zhixu transfers imports files JOB_UUID --personal --json
+ygmp zhixu transfers imports upload JOB_UUID part-000001 --file part-000001.jsonl.gz --personal --execute --json
+ygmp zhixu transfers imports preview JOB_UUID --personal --execute --json
+ygmp zhixu transfers imports confirm JOB_UUID --personal --plan-hash REVIEWED_PLAN_HASH --idempotency-key import-confirm-1 --execute --json
+ygmp zhixu transfers imports verify JOB_UUID --personal --execute --json
+```
+
+The upload command verifies the local bytes and reads the original checkpoint
+before sending a file. If the connection drops, rerun the same command on the
+same job and part. Wait for `awaiting_confirmation` after preflight and use
+`confirm` without `--execute` to review the selected plan. The CLI uses the
+transient confirmation credential internally.
+
+The MCP tool `upload_data_import_file` returns the original job and upload
+progress. Use that job UUID with `transfers imports files` and
+`transfers imports upload`. The tool does not accept file bytes or credentials.
+The authenticated upload checks the manifest digest, part length and current
+authorization before recording completion.
+
+For shared preflight and verification receipts, supply an explicit stable key
+to `transfers imports preview` or `transfers imports verify`. Repeat the same
+job, scope, action and key to read the original receipt and current status.
+
+```bash
+ygmp zhixu transfers imports preview JOB_UUID --personal --idempotency-key import-preflight-1 --execute --json
+ygmp zhixu transfers imports verify JOB_UUID --personal --idempotency-key import-verification-1 --execute --json
+```
+
+Run verification after the import completes. The shared preflight reports the
+reviewed plan digest once available. Its receipt never includes a confirmation
+credential.
+
+For a receipt shared across Agent entries, use the original-operation adapter.
+Save the reviewed digest as `{"planHash":"REVIEWED_PLAN_HASH"}` in
+`import-confirm.json`, then prepare and review the exact operation:
+
+```bash
+ygmp zhixu operations prepare --personal --action confirm_data_import --target JOB_UUID --file import-confirm.json --idempotency-key import-confirm-1 --json
+ygmp zhixu operations execute OPERATION_UUID --personal --execute --yes --json
+ygmp zhixu operations get OPERATION_UUID --personal --json
+```
+
+Use `--execute --yes` only after explicit approval of the preview. After an
+unknown response, read the original operation before taking further action.
+Its receipt points to the same import job. Organization operations use
+`--organization ORGANIZATION_UUID`.
+
+To retry a failed transfer, use its job UUID as the target. Save `{}` in
+`transfer-retry.json`. The server reads the transfer type and saved progress
+from the original job.
+
+```bash
+ygmp zhixu operations prepare --personal --action retry_data_transfer --target JOB_UUID --file transfer-retry.json --idempotency-key transfer-retry-1 --json
+ygmp zhixu operations execute OPERATION_UUID --personal --execute --yes --json
+```
+
+Review the failure and saved progress before approving. An expired execution
+window or revoked required authorization prevents the transfer from resuming.
+
+Organization creation uses your existing allowance. Prepare it in personal
+space with a JSON payload such as `{"name":"Training team"}`. An owner can
+rename an existing organization by supplying its UUID as both workspace and
+target. Review each preview before executing.
+
+```bash
+ygmp zhixu operations prepare --personal --action create_organization --file organization.json --idempotency-key organization-create-1 --json
+ygmp zhixu operations prepare --organization ORG_UUID --action update_organization --target ORG_UUID --file organization.json --idempotency-key organization-rename-1 --json
+```
+
+`export_exam_entry` uses the same original-operation flow. Prepare it in the exam's organization with `--target EXAM_UUID` and a payload such as `{"format":"png"}`. After reviewing and confirming the preview, claim the file from the same Accounts user session.
+
+```bash
+ygmp zhixu exams entry download OPERATION_UUID --organization ORG_UUID --output private-entry.png
+```
+
+The command writes a new private file and prints only its receipt metadata. File delivery expires within ten minutes and requires the entry revision and issuing access to remain valid. The existing `exams entry export` command still provides explicit private export for direct Accounts use.
+
+Personal subjective content uses the same original-operation flow:
+
+```bash
+ygmp zhixu operations prepare --personal --action create_subjective_bank --file subjective-create.json --idempotency-key subjective-content-1 --json
+ygmp zhixu operations prepare --personal --action import_subjective_archive --file subjective-archive.json --idempotency-key subjective-content-2 --json
+```
+
+Both files contain `{"input":...,"rightsConfirmed":true}` using the existing
+subjective v1 content or v2 complete archive schema. Machine credentials need
+both `banks:write` and `subjective:write`, with an explicit subjective
+`all_banks` range. Built-in grants require their independent subjective creation
+permission. No objective bank range grants subjective creation. The shared JSON
+adapter accepts up to 256 KiB of incoming payload; large file adapters remain
+pending. Imported submissions stay archived history and do not create live
+attempts, self reviews or platform AI reviews. Preserve the returned operation
+reference for execution, task reads and recovery across authorized credentials.
+
+Prepare an assistant review of an already submitted personal attempt with:
+
+```bash
+ygmp zhixu operations prepare --personal --action add_subjective_review --target ATTEMPT_UUID --file subjective-review.json --idempotency-key subjective-review-1 --json
+```
+
+The payload contains `reviewerKind: "assistant"`, `expectedRevision`, `summary`
+and one `criteria` entry per rubric item. A positive score requires a quote from
+the submitted answer. Current credentials need `banks:read`, `banks:write`,
+`subjective:read` and `subjective:write` on the owning subjective bank. The
+preview shows the score and attempt revision. Execute the same reference after
+confirmation. The submitted answer and submission time remain intact when the
+review increments the attempt revision.
+
+Read the typed receipt for a completed subjective creation, archive import, or
+assistant review with:
+
+```bash
+ygmp zhixu subjective operation-receipt opref_OPERATION_UUID --personal --json
+```
+
+Replace `OPERATION_UUID` with `operation.operationRef.id`. The `opref_` form
+supports credential handoff. An unprefixed key resolves only within the current
+credential's original operation namespace. A receipt needs current access to
+the actual subjective bank and the original action's scopes. An unresolved
+receipt preserves the original reference for later lookup. The existing
+`subjective receipt` command serves legacy user learning commands.
+
+After a lost response, read or wait on the same reference. These reads never
+retry the write. HTTP 403, missing receipts, invalid responses and timeouts do
+not establish that execution did not happen. Keep the original reference, key
+and input; do not switch credentials to prepare a replacement. Another currently
+authorized credential can read the reference and obtain a fresh preview for the
+same stored operation. Revoked credentials cannot continue. Resume accepts no
+new payload, identity or key. Other domains still use their existing task flows.
+
+The build checks exact API-exported contract bytes and the manifest digest.
+Maintainers explicitly sync from a clean committed API checkout with
+`node scripts/zhixu-contract.mjs --sync --api-root /absolute/path/to/api`.
+When unrelated work is in progress in that checkout, add
+`--source-commit <exact-full-commit-id>` to read only immutable, regular Git
+blobs from that commit. This mode never captures worktree changes. Both modes
+verify every selected artifact against the committed manifest.
+Normal builds and installed CLI commands do not read a sibling API repository.
+
+## Zhixu existing tasks
+
+`tasks get/wait/watch` reads one original typed task under current authorization.
+It never cancels, retries a write or creates a replacement. These adapters are
+implemented locally and require the new API; they are not deployed or published.
+
+```bash
+ygmp zhixu tasks get import IMPORT_UUID --personal --json
+ygmp zhixu tasks wait management_request REQUEST_UUID --organization ORGANIZATION_UUID --wait-timeout 30000 --json
+ygmp zhixu tasks watch data_export EXPORT_UUID --personal --wait-timeout 30000
+```
+
+Kinds are `import`, `data_export`, `data_import`, `management_request`,
+`maintenance_operation`, `exam_save_operation`, and `agent_run`. Use only IDs
+returned by the owning domain. Exam save uses the persistent original operation
+ID for `create_exam/edit_exam`, not an exam or request ID. `agent_run` is reserved
+and currently returns unavailable. Transfers and unlinked legacy receipts retain
+their original credential namespace; a different credential is not sufficient
+merely because it belongs to the same user.
+
+Wait and watch have a 100–60000ms polling budget after authentication and a
+100–10000ms interval. Each GET is bounded by the remaining budget. They stop on
+terminal states or `awaiting_user/reconciling`; a successful read does not mean
+the business task succeeded. Missing progress remains null. Keep the same
+reference after timeout, revocation, invalid output or an unknown result.
+
+Watch always writes JSONL, including with `--json`. Frames use
+`zhixu.task-watch/v1`, increasing `sequence`, the same `taskRef` and workspace,
+and types `snapshot`, `terminal`, `attention`, `timeout`, or `error`. Timeout and
+error exit 1; terminal and attention exit 0 as completed observations. Validation
+errors before the stream starts use ordinary CLI errors. File references require
+the owning download API to authorize delivery; they contain no signed URLs.
+
+## Zhixu exam and organization reports
+
+`exams list`, `exams get` and `exams results` require an explicit organization.
+They check anonymous API contract metadata, then use the authenticated common
+management dispatcher, including when signed in with a product JWT. These reads
+do not enroll members or settle overdue attempts. Persisted pending scores stay
+null; candidate interaction and the existing scheduled job own settlement.
+An older contract stops the CLI before its business read. Public metadata does
+not grant access; the dispatcher checks current authorization on every request.
+List/detail require `exams:read`; results require `results:read`, with the current
+owner/admin role and authorized source banks. A `canManage` field describes the
+domain role and does not grant write scopes.
+
+These read commands use the shared API report contracts and require the new API
+implementation. They are locally verified source changes, not a production or
+npm release. Existing `results:read` or `organizations:read` alone does not grant
+the new report capabilities.
+
+```bash
+ygmp zhixu exams analysis EXAM_UUID --organization ORGANIZATION_UUID --json
+ygmp zhixu exams review EXAM_UUID --organization ORGANIZATION_UUID --member MEMBER_UUID --attempt-number 1 --json
+ygmp zhixu organizations reports ORGANIZATION_UUID --json
+```
+
+Analysis requires `results:read` and `exams:analysis:read`; completed-paper review
+requires `results:read` and `exams:review:read`. Organization reports require
+`organizations:read` and `organizations:reports:read`. The server rechecks the
+current owner/admin membership, organization grant, exam bank range and retained
+data access. A selected-bank organization report counts only authorized original
+banks, not the entire enterprise.
+
+Report reads do not start, save, submit, settle or archive attempts. Review reads
+only submitted rounds and preserves the frozen question/option order. Analysis
+uses the domain's existing effective-score policy; pending settlement is not a
+new score. The CLI validates the pinned input/output and rejects a response for
+a different organization, exam, member or requested round. Revocation and scope
+loss remain failures; reads are not retried as writes or replacement tasks.
+
+## Zhixu exam editor handoff
+
+Editor drafts belong to the current customer, one explicit organization and
+`new` or an existing exam UUID. The CLI uses the same revisioned cloud draft as
+the web editor. These commands are implemented in source and local acceptance;
+they are not yet published to npm or deployed to production.
+
+```bash
+ygmp zhixu capabilities get save_exam_editor_draft --organization ORGANIZATION_UUID --target-key new --json
+ygmp zhixu exams editor-drafts get new --organization ORGANIZATION_UUID --json
+ygmp zhixu exams editor-drafts save new --organization ORGANIZATION_UUID --file editor-proposal.json --json
+ygmp zhixu exams editor-drafts save new --organization ORGANIZATION_UUID --file editor-proposal.json --execute --yes --json
+ygmp zhixu exams editor-drafts discard new --organization ORGANIZATION_UUID --expected-revision 4 --execute --yes --json
+```
+
+The proposal file contains `expectedRevision`, `baseExamRevision` and the full
+unfinished `state` from the shared schema. For an existing exam, preserve its
+known base revision. The organization and target come from command arguments;
+the file cannot override them or the current identity. Blank fields are valid
+unfinished state, and saving does not create or publish a formal exam.
+
+Save and discard default to a checked proposal without dispatching a write.
+Actual writes require an explicitly authorized `--execute --yes`; production
+also requires `--allow-prod-write`. Checks before dispatch verify the pinned
+contract and current capability. The service checks the exact revision, formal
+base and selected references again when saving. Read requires `exams:read` plus
+`exams:drafts:read`; save/discard require `exams:manage` plus `exams:drafts:write`.
+Old grants do not receive the new groups automatically.
+
+To retain an operation that the built-in assistant, CLI, or MCP can read back,
+use the shared original-operation commands. Omit `--target` for the `new`
+editor copy and pass the exam UUID for an existing exam. Use the same
+`editor-proposal.json` as above. For discard, the file contains only
+`expectedRevision`. Prepare returns a preview. Execution requires confirmation
+of that preview and the original operation ID. The durable receipt reports
+the target and revision. Read the editor copy separately for its contents.
+
+```bash
+ygmp zhixu operations prepare --organization ORGANIZATION_UUID --action save_exam_editor_draft --file editor-proposal.json --idempotency-key original-editor-save --json
+ygmp zhixu operations get OPERATION_UUID --organization ORGANIZATION_UUID --json
+```
+
+Keep the original local proposal after any uncertain write response. Read the
+same draft to reconcile it; do not substitute the latest revision into stale
+content. Identical content can be replayed with its original expected revision
+without another write. Different stale content conflicts. Discard only the
+revision the user confirmed; tombstones retain their increasing revision.
+
+The capability catalog lists all 139 target actions. An unavailable entry with
+`CAPABILITY_EVALUATOR_PENDING` declares a remaining adapter gap; catalog presence
+does not authorize execution. The CLI bundles 51 exact API contract files.
+
 ## Zhixu bank append, recycle and merge
 
 One bank can contain questions from multiple materials. Objective imports keep
@@ -208,12 +658,13 @@ ygmp zhixu banks restore BANK_UUID --personal --lifecycle-revision 1 --idempoten
 ygmp zhixu banks merge --personal --into TARGET_UUID --from SOURCE_A_UUID --from SOURCE_B_UUID --file merge-revisions.json --idempotency-key merge-banks-1 --json
 ygmp zhixu banks merged --personal --json
 ygmp zhixu banks history SOURCE_A_UUID --personal --json
+ygmp zhixu banks maintenance-sources BANK_UUID --personal --json
 ygmp zhixu banks operation --personal --idempotency-key merge-banks-1 --json
 ygmp zhixu banks operation OPERATION_UUID --personal --json
 ```
 
 For subjective banks, use the same commands under `subjective banks`, including
-`delete`, `restore`, `recycle`, `merge`, `merged`, `history` and `operation`.
+`delete`, `restore`, `recycle`, `merge`, `merged`, `history`, `maintenance-sources` and `operation`.
 This first release supports personal workspaces. New maintenance operations
 require their server-side authorization; they never use an administrator path.
 
@@ -412,3 +863,133 @@ The npm package contains a bundled executable, this README, the security
 policy, and the proprietary license. It intentionally excludes source maps,
 type declarations, repository design documents, tests, and internal operator
 documentation.
+
+
+### Shared commerce and MCP metadata reads
+
+`catalog`, `orders list` and `orders get` now use the same canonical read adapter
+as MCP and the built-in assistant. Catalog output keeps its existing `skus` key.
+These order snapshots do not generate payment links, reconcile with a provider,
+reserve a purchase, create a service request, or alter financial facts.
+
+```sh
+ygmp zhixu catalog --personal --json
+ygmp zhixu purchase eligibility --personal --json
+ygmp zhixu connections metadata --personal --json
+ygmp zhixu orders list --personal --json
+ygmp zhixu orders get ORDER_UUID --personal --json
+ygmp zhixu orders requests ORDER_UUID --personal --json
+```
+
+Order and service-request reads require an explicitly granted
+`organizations:service:read` machine scope. New personal credentials may request
+this fine-grained scope for their actual payer's records; existing organization
+credentials remain fixed to their original organization. The scope alone does
+not grant bank or organization business access. An explicit `orders list
+--organization ORG_UUID` filter also requires `organizations:read`, current owner
+or admin membership, and readable retention state. Use `--organization` for an
+organization-scoped credential. Existing `catalog`, `orders list` and `orders
+get` invocations without a scope default to personal payer metadata; the new
+`purchase eligibility`, `connections metadata` and `orders requests` commands
+require an explicit workspace. Conflicting scope flags are rejected.
+
+All reads check the pinned public contract before calling the authenticated
+common endpoint. The named `orderId` remains outside the payload, is echoed in
+the response, and is verified against the original selection. Unknown or signed
+payment results fail closed. The contract synchronizer takes the complete shared
+read list from the fixed API policy rather than maintaining another action list.
+
+`ygmp zhixu changes get CHANGE_SET_UUID --personal --json` reads a controlled
+change proposal through the same shared snapshot. Machine credentials need both
+`banks:read` and `changes:propose`, current access to the actual owning bank, and
+the existing feature availability. An expired proposal is displayed as expired
+without saving status, clearing a nonce, issuing confirmation, applying changes,
+or publishing the bank. The command verifies the original `changeSetId` in both
+the response envelope and proposal. It requires an explicit personal workspace.
+
+`ygmp zhixu changes preview-application CHANGE_SET_UUID --personal --json`
+prints a local request preview without contacting the server. Add `--execute`
+to check the current frozen proposal and rotate its temporary one-time nonce;
+production also requires `--allow-prod-write`. This credential preflight requires
+all of `banks:write`, `changes:propose`, and `changes:apply`, plus current access to
+the actual personal owning bank. Its nonce is returned only as the transient
+protocol response. No change is applied and no user approval or durable business
+operation is created. Application continues through a separately reviewed
+`operations prepare --action apply_change_set` intent containing `diffHash`,
+followed by explicit confirmation of that original operation.
+
+The `shares` commands cover six read views:
+
+```bash
+ygmp zhixu shares public SHARE_CODE --json
+ygmp zhixu shares questions SHARE_CODE MEMBER_UUID --json
+ygmp zhixu shares list --personal --json
+ygmp zhixu shares preview --banks BANK_UUID --personal --json
+ygmp zhixu shares sessions --personal --json
+ygmp zhixu shares mistakes SHARE_CODE MEMBER_UUID --personal --limit 30 --json
+```
+
+Public lookup uses the exact case-sensitive code and reads the current published
+version without sending a saved account credential. List and preview require
+current authorization for every source bank. Sessions and mistakes are bound to
+the current learner. Closed shares can remain visible in session history, while
+current content and mistakes require an active share.
+
+To create a share, put `title` and the exact `bankIds` array in the payload.
+The current personal credential needs `banks:read`, `shares:manage` and
+access to every published source. The preview identifies whether the operation
+will create a public link or reuse an existing share for that group.
+
+```bash
+ygmp zhixu operations prepare --action create_share \
+  --file share.json --idempotency-key ORIGINAL_KEY --personal --json
+```
+
+To rename, close or reopen an owned share, pass the exact share UUID and the
+current `expectedRevision` in the update payload. Include `title` and/or
+`status` (`active` or `closed`). The current credential needs `shares:manage`
+and access to every source bank.
+
+```bash
+ygmp zhixu operations prepare --action update_share --target SHARE_UUID \
+  --file update.json --idempotency-key ORIGINAL_KEY --personal --json
+ygmp zhixu operations preview OPERATION_UUID --personal --json
+```
+
+Review the returned change before explicitly authorizing execution of that
+operation. Use `operations get` with the same UUID to recover its receipt.
+
+To copy published members of a share, use the exact case-sensitive
+`shareCode`, `memberKeys`, and the member-to-version `expectedContentTokens`
+object from the public share read. Prepare the original operation with a
+personal credential that has `shares:acquire`, `banks:write`, and permission
+to create objective banks.
+
+```bash
+ygmp zhixu operations prepare --action acquire_shared_banks \
+  --file copy.json --idempotency-key ORIGINAL_KEY --personal --json
+```
+
+To prepare an unanswered practice queue, pass `shareCode`, `memberKey`,
+`contentToken` and optional practice settings with `practice:write`.
+Use `shares receipt` to recover a create, acquire or practice receipt with
+current authorization. An empty result only means the receipt was not observed.
+
+```bash
+ygmp zhixu operations prepare --action create_share_practice_session \
+  --file practice.json --idempotency-key ORIGINAL_KEY --personal --json
+ygmp zhixu shares receipt practice opref_OPERATION_UUID --personal --json
+```
+
+For personal practice, prepare a new unanswered queue with
+`create_practice_session`, the bank UUID, and a payload such as `{"count":20}`.
+Use `end_practice_session` to abandon an active session, or
+`resume_practice_session` to resume a session still frozen after its bank was
+restored. Both use the session UUID and its current `sessionRevision`. Review
+the preview and use the original operation UUID for execution and recovery.
+
+```bash
+ygmp zhixu operations prepare --action create_practice_session --target BANK_UUID \
+  --file practice.json --idempotency-key ORIGINAL_KEY --personal --json
+ygmp zhixu operations get OPERATION_UUID --personal --json
+```