@yigemo/portal 0.0.0-stage → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+YGM Studio CLI License 1.0
+
+Copyright (c) 2026 YGM Studio. All rights reserved.
+
+Permission is granted to install and use unmodified copies of this package only
+to access YGM Studio applications and services in accordance with their
+applicable terms. No source-code license is granted.
+
+You may not redistribute, sublicense, sell, modify, derive source code from, or
+use this package to create a competing service, except to the extent such a
+restriction is prohibited by applicable law. You may not remove proprietary
+notices or bypass authentication, authorization, usage, or safety controls.
+
+Third-party packages used by this software remain subject to their own license
+terms and notices.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED
+BY LAW, YGM STUDIO SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,414 @@
-# Temporary Holding Version
+# ygmp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ygmp` is the unified user and agent CLI for YGM Studio applications.
+
+The primary command name is:
+
+```bash
+ygmp
+```
+
+## Quick Start
+
+```bash
+npm install --global @yigemo/portal
+ygmp --help
+ygmp apps list
+```
+
+Run directly without a global installation:
+
+```bash
+npx --yes @yigemo/portal --help
+```
+
+## Configuration
+
+The CLI defaults to `prod` so regular product reads hit the live Chapterly
+environment. Use `--env local` or `YGMP_ENV=local` when developing against a
+local backend.
+
+The CLI can be configured with flags or environment variables. Production
+service URLs use HTTPS; local HTTP overrides are accepted only for loopback
+development targets.
+
+```bash
+YGMP_ENV=prod
+CHAPTERLY_API_BASE_URL=https://apis.lihuanyu.com
+CHAPTERLY_WEB_BASE_URL=https://chapterly.choosefire.com
+YGMP_ACCOUNTS_ISSUER=https://accounts.lihuanyu.com
+YGMP_PORTAL_CLIENT_ID=portal-cli
+YGMP_TRAVEL_API_BASE_URL=https://apis.lihuanyu.com
+YGMP_TRAVEL_WEB_BASE_URL=https://travel.choosefire.com
+YGMP_ZHIXU_API_BASE_URL=https://apis.lihuanyu.com
+YGMP_ZHIXU_WEB_BASE_URL=https://zhixu.1gemo.com
+```
+
+Equivalent flags:
+
+```bash
+ygmp \
+  --env prod \
+  --accounts-issuer https://accounts.lihuanyu.com \
+  --client-id portal-cli \
+  --api-base-url https://apis.lihuanyu.com \
+  --web-base-url https://chapterly.choosefire.com \
+  chapterly doctor --json
+```
+
+## Chapterly Examples
+
+```bash
+ygmp chapterly doctor --json
+ygmp chapterly login
+ygmp chapterly auth status
+ygmp chapterly novels list --json
+ygmp chapterly novels get 1 --json
+ygmp chapterly onboarding status 123 --json
+ygmp chapterly chapters list --novel-id 1 --json
+```
+
+Chapterly write commands default to dry-run. In `prod`, add
+`--execute --allow-prod-write` only after reviewing the dry-run output.
+
+## Zhixu enterprise services
+
+The customer `zhixu` namespace uses Accounts browser login and its own
+origin-bound credentials. It reads the same package, service and order
+contracts as the Web application. Standard tiers are 100, 300 or 1000
+enterprise members, including owners, administrators and pending members.
+Disabled members release capacity while retaining history; reactivation is
+checked again. Administrators choose exam participants from those members;
+starting, finishing or repeating an exam does not consume package seats.
+Enterprise business writes require an active service with sufficient member capacity.
+
+The additional trial package `org-trial-m5-1h` costs CNY 0.10 for one enterprise
+with five members, including its owner, for one hour. A new paid trial order
+starts a fresh hour without adding unused time; replaying the same order never
+resets it. Trial enterprises can purchase a standard package immediately.
+Use the server's `purchaseAllowedSkuCodes` to determine eligible purchases;
+trial orders cannot replace standard or historical service. At first launch,
+only 100/300-member packages and the trial accept self-service checkout;
+the 1000-member tier uses contact sales at https://1gemo.com/contact/.
+The API rejects new 1000-member orders through all customer clients.
+
+The first 30 days after formal launch offer integer CNY prices of 59/149
+for 100 members and 89/299 for 300 members (30-day/annual), then return to
+99/249 and 149/499. The explicit server-side UTC promotion window controls
+the active price version; do not hardcode the discount in the client.
+Existing orders retain their original price and entitlement snapshot.
+Historical 50-member service is preserved and renewed through manual review.
+After anyone starts an exam, administrators may only append participants and
+extend the exam window; existing personal deadlines remain unchanged.
+
+```bash
+ygmp zhixu login
+ygmp zhixu auth status --json
+ygmp zhixu catalog --json
+ygmp zhixu organizations list --json
+ygmp zhixu organizations service ORGANIZATION_UUID --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
+```
+
+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.
+
+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.
+During the offer, formal items use `2026-10-12-v4-launch` while the trial
+still uses `2026-10-12-v4`; the top-level catalog version is not a substitute
+for the selected item's version.
+
+```bash
+ygmp zhixu purchase reserve --name "Example training team" --idempotency-key first-team
+ygmp zhixu purchase checkout --organization ORGANIZATION_UUID --sku org-m100-30d --sku-version VERSION_FROM_CURRENT_CATALOG --idempotency-key purchase-1
+ygmp zhixu purchase checkout --organization ORGANIZATION_UUID --sku org-trial-m5-1h --sku-version VERSION_FROM_CURRENT_CATALOG --idempotency-key trial-1
+ygmp zhixu orders request ORDER_UUID --type plan_change --reason "Request review for 100 enterprise members" --idempotency-key change-1
+```
+
+Add `--execute` after reviewing the target and request. Production writes
+also require `--allow-prod-write`. Checkout creates an unpaid order and
+returns its payment URL; the CLI never transfers funds. Paid and fulfilled
+states are separate. Refund and package-change commands record a pending
+human request and do not automatically refund or change service.
+
+## Zhixu personal learning and subjective practice
+
+`study` reads actual personal practice evidence. Accuracy can be `null` when
+there are no scored answers; zero coverage is not a measured failure rate.
+
+```bash
+ygmp zhixu study analytics BANK_UUID --personal --window-days 30 --json
+ygmp zhixu study mistakes BANK_UUID --personal --include-stable --json
+ygmp zhixu study session SESSION_UUID --personal --json
+ygmp zhixu subjective banks list --personal --json
+ygmp zhixu subjective banks import --personal --file subjective-bank.json --rights-confirmed --idempotency-key subjective-import-1 --json
+ygmp zhixu subjective banks get BANK_UUID --personal --json
+ygmp zhixu subjective banks export BANK_UUID --personal --output bank-with-references.json --json
+ygmp zhixu subjective attempts start QUESTION_UUID --personal --idempotency-key subjective-start-1 --json
+ygmp zhixu subjective attempts save ATTEMPT_UUID --personal --file answer.txt --revision 0 --idempotency-key subjective-save-1 --json
+ygmp zhixu subjective attempts submit ATTEMPT_UUID --personal --revision 1 --idempotency-key subjective-submit-1 --json
+ygmp zhixu subjective attempts get ATTEMPT_UUID --personal --json
+ygmp zhixu subjective attempts review ATTEMPT_UUID --personal --file review.json --idempotency-key subjective-review-1 --json
+ygmp zhixu subjective receipt subjective-import-1 --personal --json
+```
+
+The export example defaults to v1 content-only author input: it excludes source
+associations and submitted learning history. Use `--format v2` for a complete
+author archive; default v1 output is not a history backup.
+
+Writes default to a server preview. After reviewing, add `--execute --yes`;
+production also requires `--allow-prod-write`. Reuse the same key and identical
+input after a timeout, or read its receipt before retrying. A new practice attempt
+needs a new key. Save before submitting; submission freezes the answer. Read the
+current revision before each subsequent save, submission or review.
+
+Imports use `zhixu.subjective-bank/v1`: `name`, `description`, and `questions`.
+Each question has unique `externalId`, `kind` (`case_analysis` or `essay`), `title`,
+`prompt`, `referenceAnswer`, and a `rubric` of unique `{id,label,maxScore}` items
+whose maximum scores sum to 100. Optional metadata includes `sourceUrl` (HTTP/S),
+`sourceNote`, `examTerm`, `suggestedMinutes` and `provenance` (`original`,
+`recollection`, `recalled-topic-training`). `officialExamPaper` is false in v1;
+recalled topics and original drills must not be presented as official papers.
+
+Review JSON contains `expectedRevision`, `reviewerKind` (`self` or `assistant`),
+`summary`, and `criteria` with one `{rubricId,score,evidence,feedback}` per rubric
+item. Nonzero scores must cite a literal excerpt from the submitted answer.
+Zero-score missing items may use “未覆盖” as evidence. Reviews are appended,
+never overwrite the submitted answer, and are reference estimates rather than
+official exam grades. Subjective estimates stay separate from objective accuracy.
+The CLI stores the caller's explicit review; it does not perform automatic grading.
+Bank export includes the author's reference answers; practice reads hide them
+until submission. Exports use private new files and never overwrite existing ones.
+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 bank append, recycle and merge
+
+One bank can contain questions from multiple materials. Objective imports keep
+using `imports create --bank BANK_UUID`; subjective append targets an existing
+bank and accepts a JSON array of 1–200 questions using the question format above.
+Use a stable source namespace when appending the same material again. The server
+reviews duplicates and source conflicts without changing old answers or reviews.
+
+```bash
+ygmp zhixu subjective banks append BANK_UUID --personal --file questions.json --namespace paper-2022-cases --content-revision 3 --rights-confirmed --idempotency-key append-paper-2022 --json
+ygmp zhixu subjective banks questions BANK_UUID --personal --content-revision 4 --limit 200 --json
+ygmp zhixu banks delete BANK_UUID --personal --content-revision 3 --lifecycle-revision 0 --idempotency-key recycle-bank-1 --json
+ygmp zhixu banks recycle --personal --json
+ygmp zhixu banks restore BANK_UUID --personal --lifecycle-revision 1 --idempotency-key restore-bank-1 --json
+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 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`.
+This first release supports personal workspaces. New maintenance operations
+require their server-side authorization; they never use an administrator path.
+
+`delete` means moving the bank to its **30-day recycle bin**. It is not permanent
+deletion. Recovery preserves IDs and learning records, while closed public shares
+stay closed. Merge retains distinct question IDs and learning history; source
+banks become read-only history anchors. It does not deduplicate different IDs or
+provide an automatic split after a successful merge.
+
+Read current revisions from bank or recycle metadata. Merge revisions must match
+the exact ordered `--from` list:
+
+```json
+{
+  "target": {"contentRevision": 3, "lifecycleRevision": 0},
+  "sources": [
+    {"id": "SOURCE_A_UUID", "contentRevision": 2, "lifecycleRevision": 0},
+    {"id": "SOURCE_B_UUID", "contentRevision": 1, "lifecycleRevision": 0}
+  ]
+}
+```
+
+The UUID labels above are placeholders. Maintenance writes default to a real
+server preview. Review its blockers, aliases, question counts, sharing and grant
+effects before using `--execute --confirmation-token TOKEN`. For an already
+authorized immediate preview and execution, use `--execute --yes` instead.
+Production also requires `--allow-prod-write`. Confirmation is tied to the same
+account, input and revisions; a changed bank requires a fresh preview.
+
+On an uncertain write response, the CLI queries the original read receipt and
+returns `ZHIXU_WRITE_RESULT_UNKNOWN` with its status and optional operation ID.
+It never retries the write automatically. Inspect `banks operation` using the
+original key before retrying the identical request with that same key.
+
+Question pagination requires the same `contentRevision` on every page. Continue
+with the returned `nextCursor`; a revision conflict requires fresh metadata and
+a new traversal. Legacy full-bank reads over their response limit return
+`SUBJECTIVE_PAGINATION_REQUIRED` rather than silently returning only 200 questions.
+
+For a large bank or its submitted learning history, export a complete private
+author archive with `subjective banks export BANK_UUID --personal --format v2
+--content-revision REVISION --output archive.json`. The CLI streams all pages,
+reuses the first page's server snapshot, and removes partial output if a revision,
+snapshot, cursor or question identity changes. `--page-size` defaults to 20 and
+accepts 1–200. Oversized responses fail explicitly; they are never truncated.
+The complete archive package is limited to 2,000 questions and 20 MiB, including
+history and metadata. Exceeding either limit fails the whole export and removes
+its output. This does not limit bank size: question pagination still reads the
+full bank. This release does not automatically split banks or archive packages.
+
+This `zhixu.subjective-bank/v2` archive includes source metadata and submitted
+answers/reviews at `capturedAt`. It excludes drafts and temporary snapshot tokens.
+It is an author archive, not v1 import input or a replay of official learning
+facts. `subjective banks import --file archive.json` recognizes a complete v2
+archive and uses the separate customer archive-import endpoint, with a limit of
+2,000 questions and 20 MiB. It creates new bank/question identities and stores old
+answers, reviews and provenance in a separate archive; it never generates formal
+attempts, restores source-file access or inflates mastery. Re-exported archives
+preserve these entries in `archivedHistory`. Imports keep the same default preview,
+rights confirmation, `--execute --yes`, operation-key and production safeguards.
+The v1 import format and its 200-question / 2,000,000-byte limit stay compatible.
+
+## Zhixu management and integrations
+
+Question-bank, import, member, position and exam commands share the product's
+authorization, validation and published-version rules. Select `--personal` or
+`--organization UUID` on every bank, import and exam command. Organization
+member commands use the organization UUID in their path.
+
+New writes default to a real server dry-run. Use a stable 8–100 character
+`--idempotency-key`; retry the same operation with the same key and input.
+Publication, bulk review, member confirmation, status and position changes,
+exam publication, added participants and cancellation need a confirmation
+token from a matching preview. For an already authorized operation,
+`--execute --yes` obtains that preview and immediately executes the same input.
+Production writes also require `--allow-prod-write`.
+
+```bash
+ygmp zhixu auth refresh --json
+ygmp zhixu banks list --organization ORGANIZATION_UUID --json
+ygmp zhixu banks create --organization ORGANIZATION_UUID --file bank.json --idempotency-key bank-create-1 --json
+ygmp zhixu imports create --bank BANK_UUID --organization ORGANIZATION_UUID --file questions.docx --format docx --rights-confirmed --idempotency-key docx-import-1 --json
+ygmp zhixu imports get IMPORT_UUID --organization ORGANIZATION_UUID --json
+ygmp zhixu candidates list --import IMPORT_UUID --organization ORGANIZATION_UUID --json
+ygmp zhixu candidates review CANDIDATE_UUID --organization ORGANIZATION_UUID --action accept --row-version ROW_VERSION --idempotency-key candidate-review-1 --json
+ygmp zhixu imports publish IMPORT_UUID --organization ORGANIZATION_UUID --working-revision WORKING_REVISION --idempotency-key import-publish-1 --json
+ygmp zhixu organizations member-imports template ORGANIZATION_UUID --output members.xlsx --json
+ygmp zhixu organizations member-imports create ORGANIZATION_UUID --file members.xlsx --format xlsx --idempotency-key member-import-1 --json
+ygmp zhixu organizations member-imports get ORGANIZATION_UUID BATCH_UUID --json
+ygmp zhixu organizations member-imports confirm ORGANIZATION_UUID BATCH_UUID --idempotency-key member-confirm-1 --json
+ygmp zhixu organizations positions list ORGANIZATION_UUID --json
+ygmp zhixu exams create --organization ORGANIZATION_UUID --file exam.json --idempotency-key exam-create-1 --json
+ygmp zhixu exams publish EXAM_UUID --organization ORGANIZATION_UUID --idempotency-key exam-publish-1 --json
+ygmp zhixu exams results EXAM_UUID --organization ORGANIZATION_UUID --output results.json --json
+ygmp zhixu exams results EXAM_UUID --organization ORGANIZATION_UUID --format csv --output results.csv --json
+```
+
+`bank.json` can be `{"name":"Training bank","usageMode":"practice_and_exam"}`.
+Use each command's `--help` for input fields and concurrency revisions.
+Prepared question imports accept JSON arrays or JSONL following
+`zhixu.question-candidate/v1` with source locators. DOCX/prepared sources are
+limited to 20 MB and prepared arrays to 20,000 candidates. Member XLSX uses the
+template, with a 2 MB/500-person limit; prepared member JSON accepts up to 1000
+rows. Import creation, review and publication are separate actions. File
+preflight checks metadata and permissions; candidate validation follows the
+versioned contract. Exports create exclusive 0600 files. CSV escapes spreadsheet
+formulas, quotes and line breaks.
+
+Initial member passwords, when allowed for an Accounts customer session, are
+read only from a private input file and redacted in previews and errors.
+API credentials and AI connections cannot set member passwords. The CLI does
+not replace a candidate's row version, a bank's working revision or an exam's
+revision after a conflict.
+
+If a write result is uncertain, read its original receipt before retrying:
+
+```bash
+ygmp zhixu requests get --action create_bank --organization ORGANIZATION_UUID --idempotency-key bank-create-1 --json
+```
+
+External systems use scoped API credentials created with a real Accounts
+session. Credentials bind to a personal workspace or one enterprise, selected
+scopes and optionally selected banks; they expire after 1–90 days (default 30)
+and can be revoked. The server checks current enterprise permissions on each
+request. A credential input is:
+
+```json
+{"name":"training-system","scopes":["banks:read","exams:read","results:read"],"bankScopeMode":"all_banks","bankIds":[],"expiresInDays":30}
+```
+
+```bash
+ygmp zhixu tokens create --organization ORGANIZATION_UUID --file credential.json --output training-token.txt --idempotency-key token-create-1 --json
+# Once authorized, add --execute --yes --allow-prod-write.
+ygmp zhixu tokens list --organization ORGANIZATION_UUID --json
+ygmp zhixu tokens revoke CREDENTIAL_UUID --organization ORGANIZATION_UUID --idempotency-key token-revoke-1 --json
+```
+
+Tokens are returned once. Execution requires an exclusive private output file
+or explicit `--show-secret`; ordinary JSON output contains only metadata.
+Replaying creation returns `alreadyIssued` metadata without another secret.
+Supply the stored token using `YGMP_ZHIXU_ACCESS_TOKEN` for CLI calls, or a
+Bearer header and `X-Organization-Id` in an independent HTTP client. Unified
+management writes use `POST /question-bank/management/actions` with
+`action`, `organizationId`, optional `targetId`, `payload`, `dryRun` and
+`idempotencyKey`; important execution also supplies `confirm: true` and the
+matching `confirmationToken`.
+
+## Travel MCP
+
+Travel support is intentionally limited to the existing short-lived Agent
+handoff flow. It does not log in to a Travel account, list trips, apply a
+proposal, or expose a remote MCP endpoint.
+
+Run readiness checks or start the local stdio server:
+
+```bash
+ygmp travel doctor --json
+ygmp travel mcp serve
+```
+
+Print host configuration without changing host files:
+
+```bash
+ygmp travel mcp config --client codex
+ygmp travel mcp config --client claude-desktop
+ygmp travel mcp config --client openclaw
+```
+
+For the Codex CLI currently verified on this machine, the generated command is:
+
+```bash
+codex mcp add travel --env YGMP_TRAVEL_MCP_CLIENT=codex -- ygmp travel mcp serve
+```
+
+Claude Desktop and OpenClaw output a generic `mcpServers.travel` JSON object
+with the same `ygmp travel mcp serve` command and their restricted client
+identity value. Review where each host expects that JSON; `ygmp` never edits
+the host configuration.
+
+The MCP server exposes exactly:
+
+```text
+travel_handoff_get_context({ handoffId, token })
+travel_handoff_submit_proposal({ handoffId, idempotencyKey, proposal })
+```
+
+The first successful context call retains its token only in the current MCP
+process and only until the handoff expires. Do not put a handoff token in an
+environment variable, MCP configuration, command line, URL, or token store.
+The submission tool only creates a candidate; the user must review and confirm
+it in Travel Web.
+
+## Distribution
+
+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.

package/SECURITY.md

@@ -0,0 +1,10 @@
+# Security Policy
+
+## Credentials
+
+- Never place application or handoff credentials in command-line arguments, URLs, repositories, MCP configuration, or issue reports.
+- Travel handoff credentials are short-lived and retained only by the running local MCP process.
+
+## Reporting
+
+Report security issues privately to YGM Studio maintainers. Do not publish credentials, exploit details, private endpoints, or user data in a public issue.