Add files via upload

docs/en-US/contributing-guide.md

@@ -0,0 +1,115 @@
+# Contributing Guide
+
+[中文](../zh-CN/contributing-guide.md)
+
+This guide defines baseline expectations when adding features, APIs, tools, frontend pages, or docs.
+
+## Principles
+
+- New features need documentation.
+- New APIs need OpenAPI updates.
+- New frontend text needs zh-CN and en-US i18n.
+- New config must state hot-apply behavior.
+- New high-risk tools must define HITL policy.
+- New DB fields must be compatible with old databases.
+- New long-running tasks need state, cancellation, or recovery strategy.
+
+## New API Checklist
+
+- Handler validates parameters.
+- Error response has stable `error` and readable `message`.
+- Endpoint is authenticated unless it is an explicit platform callback.
+- Mutations write audit events.
+- Long tasks write monitoring/task state.
+- `internal/handler/openapi.go` updated.
+- API docs or recipes updated.
+- Handler tests added.
+
+## New Config Checklist
+
+- Field exists in `config.Config`.
+- `config.yaml` sample has comments.
+- Safe default when omitted.
+- Old configs still start.
+- Hot-apply behavior documented.
+- Web settings do not delete unknown fields.
+- Security docs updated if high-risk capability is affected.
+
+## New Tool Checklist
+
+For YAML tools and Go MCP tools:
+
+- stable and specific tool name;
+- searchable `short_description`;
+- explicit input schema, not one raw `cmd`;
+- readable and stable output;
+- controlled timeout and error path;
+- high-risk operation not globally allowlisted;
+- docs explain use case and risk.
+
+## New Frontend Page Checklist
+
+- Reuse `apiFetch`, modal, notifications, and existing state patterns.
+- Add all visible text to `zh-CN.json` and `en-US.json`.
+- Include loading, empty, and error states.
+- Confirm destructive/high-risk actions.
+- Avoid overflow in long English labels.
+- Browser console clean.
+
+## DB Change Checklist
+
+- Migration is idempotent.
+- Old DB upgrades.
+- Defaults are safe.
+- Large indexes are deliberate.
+- Empty DB and old DB tested.
+- Release notes mention backup.
+
+## High-Risk Capability Checklist
+
+High-risk includes Shell, WebShell, C2, external MCP write/execute, credential access, and bulk scanning.
+
+Answer:
+
+- Who can call it?
+- Does it require HITL?
+- What is audited?
+- How can it be cancelled?
+- How is cleanup done?
+- How can it be disabled?
+- Is it off by default?
+
+## Documentation Requirements
+
+Each important feature should document:
+
+- purpose;
+- config;
+- workflow;
+- risk boundary;
+- troubleshooting;
+- source anchors.
+
+Chinese and English docs must have matching filenames:
+
+```text
+docs/zh-CN/
+docs/en-US/
+```
+
+Update:
+
+- `docs/README.md`
+- `docs/zh-CN/README.md`
+- `docs/en-US/README.md`
+
+## Review Focus
+
+Prioritize:
+
+- behavior regressions;
+- security boundaries;
+- old data compatibility;
+- error handling;
+- test gaps;
+- docs and OpenAPI sync.