docs(plugins): publish Plugin V1 format contract, schemas and a dependency-free public validator

docs/community/groups.md

@@ -0,0 +1,87 @@
+# Community groups
+
+This document defines the three community layers, what each layer is for, and the rule for moving
+between them. It is public so that joining a group is a predictable decision rather than a guess.
+
+## Layers
+
+| Layer | Who can join | What belongs there | What does not |
+| --- | --- | --- | --- |
+| Newcomer | Anyone with the group QR code or the Discord link | Install, configuration, first-run usage, frequently asked questions | Unreleased features, internal roadmap, internal test builds |
+| Advanced | Anyone who has opened at least one issue, or who is invited | Architecture discussion, PR intentions, performance findings, design proposals | Internal roadmap, unreleased features |
+| Insider | Invitation only, after signing the external-disclosure rule | Test builds, unreleased features, early feedback | Screenshots of accounts, session identifiers, or unreleased versions |
+
+The three layers are rules first and separate groups second. A new group with fewer than 50 active
+members is not created; the rule applies to the existing group until the volume justifies a split.
+
+## The one entry point
+
+Every layer carries the same pinned card, pointing at the same three places:
+
+1. **Report an issue** — `https://github.com/MiniMax-AI/minimax-code/issues/new/choose`
+2. **Claim a task** — the `good first issue` label:
+   `https://github.com/MiniMax-AI/minimax-code/labels/good%20first%20issue`
+3. **See the on-call rota and the weekly replay** — [Community on-call](oncall.md)
+
+Feedback posted in chat without an issue number is not tracked. If a chat report is not converted into
+an issue within 24 hours, the on-call owner raises it on the reporter's behalf.
+
+## Moving between layers
+
+- **Newcomer → Advanced**: automatic, as soon as the member opens an issue or is invited. There is no
+  application and no approval.
+- **Advanced → Insider**: invitation only. The invite includes the external-disclosure rule below, and
+  the rule is acknowledged before any test build is shared.
+- **Insider → public**: content returns to a public layer only through the formal release notes. Chat
+  history is never the source for external material.
+
+## External-disclosure rule for the Insider layer
+
+Acknowledged by every Insider member before receiving a test build.
+
+1. Test builds, unreleased feature names, and internal version numbers stay in the Insider layer. They
+   are not posted to a public group, a public issue, a screenshot, a blog post, or a video.
+2. Account identifiers, session identifiers, tokens, and customer project content are never shared in
+   any layer. Use synthetic files and dedicated test accounts.
+3. External material about a feature comes from the release notes for a released version, not from a
+   chat log. If a screenshot is needed for a public post, it must be regenerated from a released
+   build.
+4. A leak is reported to the release coordinator immediately, and the affected material is withdrawn
+   as soon as it is identified. Reporting a leak is never held against the reporter.
+
+## What a layer may be used for
+
+| Activity | Newcomer | Advanced | Insider |
+| --- | --- | --- | --- |
+| Install and configuration help | Yes | Yes | Yes |
+| Bug report and question answering | Yes | Yes | Yes |
+| Weekly feedback replay | Yes | Yes | Yes |
+| AMA session (biweekly) | Yes | Yes | Yes |
+| Showcase wall submission | Yes | Yes | Yes |
+| Architecture and design discussion | No | Yes | Yes |
+| Pull request review participation | No | On invitation | Yes |
+| Test build distribution | No | No | Yes |
+
+## Showcase wall
+
+Showcases are collected in `docs/showcase/` and mirrored to a GitHub Discussions category.
+
+- **Threshold:** a showcase must be runnable — a repository, or a prompt that reproduces it, plus the
+  verification command. Screenshots alone are not accepted.
+- **Every showcase produces a task.** Each accepted showcase must yield at least one
+  `good first issue` task, by extracting the step a newcomer could do independently. This is the point
+  of the wall: a showcase that produces no task brings in visitors who find nothing to do.
+- **Low bar by design:** the entry requirement is "post a prompt that runs". A showcase is not a
+  product pitch.
+
+## AMA sessions
+
+Biweekly, 30 minutes: 20 minutes of product questions, 10 minutes walking through live issues.
+
+- **Agenda comes from the queue.** Every question discussed is drawn from the current
+  `needs-triage` queue or a contribution request. The host does not choose topics independently.
+- **Recording and minutes** are archived to the Discussions `AMA` category, with the issue numbers
+  discussed listed in the minutes.
+- **Failure condition:** if three consecutive sessions draw fewer than 30% of registrants, the format
+  changes to a smaller closed-door session over live issues instead of a public AMA. Adding more
+  sessions is not the response.

docs/community/oncall.md

@@ -0,0 +1,156 @@
+# Community on-call and issue SLA
+
+This document defines who watches the community channels, what counts as a response, and how
+feedback is replayed back to reporters. It is a public commitment: anyone reading it should be able
+to predict when they will hear back.
+
+## Scope
+
+The community on-call covers two surfaces:
+
+| Surface | Meaning | Owner |
+| --- | --- | --- |
+| Community chat (Chinese Feishu group, Discord) | User questions, feedback, event coordination | On-call A |
+| GitHub issues (`MiniMax-AI/minimax-code`) | Bug reports, feature requests, contribution requests | On-call B |
+
+These are two different roles and they are staffed by two different people. A single person holding
+both roles cannot cover the 18:00–20:00 window, so that window is explicitly not covered by either
+role.
+
+## Rotation
+
+| Role | Window | Timezone | Coverage |
+| --- | --- | --- | --- |
+| On-call A | Weekdays 10:00–18:00 | Asia/Shanghai | Community chat |
+| On-call B | Daily 09:00, 20:00–23:00, and weekends | Asia/Shanghai | GitHub issues |
+| Uncovered | 18:00–20:00 weekdays | — | Neither role; escalate to the release coordinator |
+
+The rotation is published in the community chat as a pinned card. It is replaced every two weeks.
+
+## Response SLA
+
+**Every open issue must receive a triage action within 48 hours of being opened.** A triage action is
+one of the following, and one of them counts:
+
+- applying a type and product label;
+- asking the reporter for the specific missing information (`needs-info`);
+- linking a duplicate to its original issue;
+- recording a next step in a comment, including a decision to decline with a reason.
+
+A triage action is not a promise to fix or to ship in a release. Classification alone does not commit
+the project to a delivery date, and this distinction is stated in every response so reporters know
+what they are getting.
+
+Anything that has been open for more than 48 hours without any of the above is a SLA breach and is
+listed in the weekly feedback replay.
+
+## Label hygiene
+
+- An issue must not stay on `needs-triage` after it is closed. When closing an issue, remove
+  `needs-triage` in the same action.
+- `needs-triage` counts only open issues. Reporting a `needs-triage` ratio that includes closed
+  issues overstates the backlog; the canonical number is `is:issue is:open label:needs-triage`.
+- When an issue is closed as `duplicate` or `wontfix`, the reason is stated in a comment, per the
+  triage policy in [Maintainers](../maintainers.md).
+
+## Contribution requests
+
+A request for repository access is a request for a decision, and a decision must be communicated.
+Even when the answer is "no", the answer is sent.
+
+- Tag contribution requests with `contribution-request` so the funnel from request to decision is
+  measurable.
+- Respond within 48 hours with one of: approved, declined with a reason, or already completed
+  internally.
+- **When the underlying task is completed internally first, the requester is told explicitly and their
+  fork and branch are still declared valid.** If the internal fix missed anything, the requester is
+  invited to open a fork PR. Silently closing a contribution request because the work was done
+  elsewhere is treated as a SLA breach, not as resolution.
+- Submission of a fork PR does not require collaborator access. Access is a convenience for
+  maintainers, not a precondition for contributing.
+
+## Weekly feedback replay
+
+Every Friday, the on-call owner posts a single message to the community chat summarising the week:
+
+- every issue that received a triage action, with its number and what the action was;
+- every issue that was asked for more information, and what is still needed;
+- every issue that was closed, and why;
+- every open issue that has breached the 48-hour SLA, listed by number.
+
+The replay links issue numbers directly. It exists so that a reporter can see what happened to their
+report without having to ask, and it is the mechanism that keeps feedback from being silently dropped.
+
+## Reply templates
+
+### Triage response
+
+```
+Thanks for the report — received and triaged.
+
+Triage action: <label / needs-info / duplicate / next step recorded>, removed from `needs-triage`.
+
+What we need from you to take this further:
+1. <specific question>
+2. <specific question>
+
+We will reply within 48 hours. This triage action is not a commitment to a release date.
+```
+
+### Contribution request — already completed internally
+
+```
+Thanks for the patch and for following the contribution route. Sorry for the long silence on this
+thread; that was our failure, not yours.
+
+The task you prepared for (#<n>) was completed internally by #<n> and #<n>, so that specific task is no
+longer open.
+
+Your fork and branch are still valid. If you spot anything the internal fix missed or got wrong,
+please open a fork PR — no collaborator access is required to submit a fork PR, and we review it
+within 48 hours. The same applies to any other change you have prepared.
+
+If you would like to pick up a scoped task, the `good first issue` label is the canonical list:
+<label url> — items there are expected to be independently completable, with
+`pnpm verify --profile docs` as the verification command for documentation tasks.
+```
+
+The two sentences that matter here are the second and third paragraphs. Reporting that the work was
+done elsewhere, and then stating that the requester's work is still valid, is what keeps a second
+applicant from being treated the same way. Never write "the task is already done, please resubmit".
+
+### Contribution request — approved
+
+```
+Approved. You now have the requested access.
+
+The change is expected to be scoped in an issue first, then submitted as a PR from your fork.
+Please run the verification command for the profile that covers your change
+(`pnpm verify --profile docs` for documentation) and paste the real command output into the PR
+description. Review target is 48 hours; if you have not heard back by then, ping the on-call owner.
+```
+
+### Security-relevant report
+
+```
+Thank you for the detailed report. This is treated as a safety-priority report and escalated for a
+code-level review.
+
+Please do not post further exploit detail in this public thread. If the reproduction involves a
+pattern that could affect other users, open a private report per SECURITY.md and reference this issue
+number.
+
+We will reply within 48 hours.
+```
+
+## Reporting
+
+The on-call owner reports these numbers weekly to the community chat and to the project maintainers:
+
+| Metric | Definition |
+| --- | --- |
+| 48h triage coverage | share of issues opened in the week that received a triage action within 48 hours |
+| Open `needs-triage` | open issues still carrying `needs-triage` (open scope only) |
+| SLA breaches | issues open for more than 48 hours with no triage action |
+| Zero-reply issues | open issues with no comment at all |
+| Contribution request resolution time | hours from request to a communicated decision |

docs/plugins/README.md

@@ -0,0 +1,100 @@
+# 写一个 MiniMax Code Plugin
+
+本文是外部作者的上手路径：从零到一个可提交校验的 Plugin 包。目标是让你在本地
+就能跑出与官方 CI 同一条校验命令，避免提交后才发现格式问题。
+
+## 1. 先跑通环境
+
+```bash
+git clone https://github.com/MiniMax-AI/minimax-code.git
+cd minimax-code
+pnpm install
+pnpm verify --profile docs
+```
+
+最后一条必须先通过。它验证的是本仓库自身的公开边界，能跑通说明你的环境是对的——
+这是整条路径的信任锚点。
+
+## 2. 创建一个 Plugin 包
+
+一个 Plugin 是一个独立目录，根下必须有 `.minimax-plugin/plugin.json`：
+
+```text
+my-plugin/
+  .minimax-plugin/plugin.json
+  skills/research/SKILL.md
+  my-tool.mcp.json
+```
+
+最小的 manifest：
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "一句话说明这个 Plugin 做什么。",
+  "author": "你的名字或组织",
+  "icon": "icon.png",
+  "category": "Code",
+  "exampleQueries": ["用它做一件具体的事"],
+  "apps": [],
+  "mcpServers": ["my-tool.mcp.json"],
+  "skills": ["skills/research/SKILL.md"]
+}
+```
+
+`name` 必须与目录名一致。`category` 只能取 `Office`、`Studio`、`Design & Sites`、
+`Code`、`Business`、`Sales`、`Productivity`、`Science & Healthcare`、`Education`、`Other`。
+`apps`、`mcpServers`、`skills`、`hooks` 至少有一项非空。
+
+完整字段与约束见 [Plugin 包格式 V1](package-format-v1.md)。
+
+## 3. 本地校验
+
+```bash
+node tools/plugins/validate-plugin.mjs path/to/my-plugin
+```
+
+或用仓库脚本：
+
+```bash
+pnpm check:plugin path/to/my-plugin
+```
+
+这条校验与 `pnpm verify --profile docs` 内部执行的是**同一段代码**，所以本地通过
+意味着 CI 也会通过。它会检查：
+
+- manifest 是否满足 `schemas/plugins/plugin-v1.schema.json`
+- 被引用的 App / MCP / Hook 文件是否存在且满足各自 schema
+- 每个 Skill 的 frontmatter 是否包含与目录一致的 `name` 和非空 `description`
+- 路径是否为 V1 允许的 portable ASCII path（禁止绝对路径、`..`、反斜杠、Windows 保留名）
+
+退出码 `0` 表示通过，`1` 表示发现问题，`2` 表示用法错误。
+
+## 4. 提交
+
+通过校验后按仓库的贡献流程提交 Plugin：先开 issue 描述你的 Plugin 与改动范围，
+再从 fork 提 PR。PR 描述里请贴上 `validate-plugin.mjs` 的真实输出。
+
+## 5. 这条校验不覆盖什么
+
+本地校验**不等于**发布通过。以下由官方 Marketplace validator 在提交时执行：
+
+- catalog 成员资格（Plugin 是否进入官方目录）
+- 跨文件能力闭合（manifest 引用与实际文件树完全一致）
+- archive 体积与 entry 上限、`content_digest` 计算
+- icon 与 Showcase 媒体的真实字节校验
+
+因此请不要把本地校验通过理解为"可以直接上架"。它保证的是包**格式正确**，
+而不是包**内容合格**。
+
+## 6. 参考
+
+| 主题 | 文档 |
+| --- | --- |
+| 包格式、路径契约、安全上限、digest | [package-format-v1.md](package-format-v1.md) |
+| Host Binding 扩展 | [host-bindings.md](host-bindings.md) |
+| Showcase 案例配置 | [showcases.md](showcases.md) |
+| JSON Schema | `schemas/plugins/` |
+| 路径与 digest 参考向量 | `test-vectors/plugins/` |