docs(runtime): add bilingual YAML field reference, sample, CI gate notes

Three documentation gaps surfaced while landing the PR4-6 runtime work:

1. The YAML schema chapter in docs/{en,zh}/runtime.md only pointed at an
   external design doc (projects/.../runtime-cli-design.md), which is
   useless to end users reading the published reference.
2. There was no copy-pasteable starter spec to pair with `ar runtime apply`.
3. AGENTS.md only mentioned `make lint`; the actual CI gate also runs
   ruff format --check, mypy, and the 95%-coverage pytest job — local
   contributors had no signal that those were blocking.

Changes:

- docs/{en,zh}/runtime-yaml.md (new): field-level reference covering
  every key the parser accepts. Sections for metadata, container,
  registryConfig, resources, protocol, network, healthCheck, log, env,
  nas, ossMount, endpoints/scaling; CLI auto-injection rules
  (system_tags, artifact_type, default endpoint); exhaustive validation
  table mirroring agentruntime_yaml.py; runnable minimal / production
  (ACREE + private network + NAS + canary) / custom-registry examples;
  YAML -> SDK field map. EN/ZH mirrored 1:1 per AGENTS.md doc parity.
  diskSize is documented as MB (not GB, which the design doc had wrong).

- docs/{en,zh}/runtime.md: replace the external design-doc pointer with
  a link to runtime-yaml.md.

- docs/{en,zh}/index.md: add the YAML reference next to runtime.md in
  the command-groups table.

- agentruntime.yaml (new, repo root): runnable starter spec mirroring
  superagent.yaml's placement. Renders cleanly via
  `ar runtime render -f agentruntime.yaml`. Commented-out blocks point
  at the common optional knobs (VPC, SLS log, scaling).

- AGENTS.md:
  - "CI Lint Gate" section listing all four blocking checks (ruff check,
    ruff format --check, mypy, pytest --cov-fail-under=95) with the
    local commands and Make targets that reproduce CI.
  - Commands block updated with make format-check, `mypy src/agentrun_cli`,
    and `make coverage`.
  - Docs layout diagram updated to include runtime.md / runtime-yaml.md.

Signed-off-by: Sodawyx <sodawyx@126.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Sodawyx <sodawyx@126.com>

Author: Sodawyx

AGENTS.md

@@ -14,8 +14,12 @@ make dev                  # Create venv + install editable with dev deps
 make install              # Install without dev deps
 
 # Development
-make lint                 # Run ruff linter
+make lint                 # Run ruff linter (ruff check)
+make format-check         # Verify code is ruff-formatted (no rewrite)
+.venv/bin/ruff format src/ tests/   # Apply ruff formatting in place
+.venv/bin/mypy src/agentrun_cli     # Static type check (CI runs this verbatim)
 make test                 # Run all tests
+make coverage             # Run tests with the >=95% coverage gate (matches CI)
 .venv/bin/pytest tests/test_cli_basic.py -v              # Run a single test file
 .venv/bin/pytest tests/test_cli_basic.py::TestConfigCommands::test_set_and_get -v  # Single test
 
@@ -41,6 +45,42 @@ make build-all            # macOS + Linux (via Docker)
 
 **Error handling** (`_utils/error.py`): The `@handle_errors` decorator catches SDK exceptions by class name pattern (no hard import) and maps them to deterministic exit codes (0=success, 1=not found, 2=bad input, 3=auth, 4=server). Errors go to stderr as JSON.
 
+## CI Lint Gate (must pass locally before pushing)
+
+The GitHub Actions `CI` workflow (`.github/workflows/ci.yml`) blocks merges on
+**all four** of these checks, run in dedicated jobs against Python 3.10–3.13.
+Run them locally before pushing — failing any one of them produces a red PR.
+
+| CI job | Command (run from repo root) | Make target |
+|---|---|---|
+| Lint (ruff) — lint rules | `ruff check src/ tests/` | `make lint` |
+| Lint (ruff) — format check | `ruff format --check src/ tests/` | `make format-check` |
+| Type check (mypy) | `mypy src/agentrun_cli` | *(no make target — run directly)* |
+| Test + coverage | `pytest tests/unit tests/integration --cov=agentrun_cli --cov-fail-under=95` | `make coverage` |
+
+Rules:
+
+- **Ruff format is non-negotiable.** CI runs `ruff format --check`, not
+  `ruff format` — it will not auto-fix. Run `ruff format src/ tests/` locally
+  (or `make format-check` to verify) before every commit. Configuration lives
+  in `pyproject.toml` under `[tool.ruff]`.
+- **Mypy must stay green.** Mypy config is in `pyproject.toml` under
+  `[tool.mypy]` (`python_version = "3.10"`, `warn_unreachable = true`,
+  `ignore_missing_imports = true`). Prefer narrowing types (`cast`, explicit
+  annotations) over `# type: ignore`; suppressions need a `[code]` selector
+  and a one-line comment justifying them.
+- **Coverage threshold is 95%.** Every code change must keep incremental
+  coverage at or above 95% — `make coverage` enforces it. A Claude Code hook
+  (`.claude/settings.json`) also runs this automatically after edits to
+  `src/` files. See [Integration Test Requirement](#integration-test-requirement)
+  for the test-coverage rules that feed this gate.
+- **No `--no-verify` / `--no-gpg-sign` shortcuts.** If a hook or lint check
+  fails, fix the underlying issue and create a new commit.
+
+The CI workflow also runs a Smoke job on macOS + Windows (`make build` of the
+PyInstaller binary) and a `pip-audit` security scan — both are advisory but
+should not regress.
+
 ## Testing
 
 Tests use `click.testing.CliRunner` and `unittest.mock.patch` to swap `CONFIG_FILE`/`CONFIG_DIR` with `tmp_path` fixtures, so no real `~/.agentrun/` is touched. Model commands that hit the SDK are not tested in the basic suite — they require credentials.
@@ -83,6 +123,8 @@ docs/
 │   ├── index.md     # install / auth / global options / output / exit codes / group nav
 │   ├── config.md    # one file per command group
 │   ├── model.md
+│   ├── runtime.md
+│   ├── runtime-yaml.md   # detailed YAML field reference for `ar runtime apply`
 │   ├── sandbox.md
 │   ├── skill.md
 │   ├── super-agent.md

agentruntime.yaml

@@ -0,0 +1,52 @@
+# Sample AgentRuntime spec for `ar runtime apply -f agentruntime.yaml`.
+# Full field reference: docs/en/runtime-yaml.md (zh: docs/zh/runtime-yaml.md)
+#
+# Quick usage:
+#   ar runtime render -f agentruntime.yaml   # dry-run, prints SDK input
+#   ar runtime apply  -f agentruntime.yaml   # create-or-update, waits to READY
+#
+# The CLI auto-injects system_tags=["x-agentrun-cli"] and artifact_type=Container.
+# When spec.endpoints is omitted, a default endpoint (targetVersion=LATEST) is
+# also injected — this sample defines an explicit one to make the shape clear.
+
+apiVersion: agentrun/v1
+kind: AgentRuntime
+
+metadata:
+  name: my-agent                          # required, matches [a-z0-9-]{1,63}
+  description: "Example AgentRuntime"
+  # workspace: default                    # optional; mutually exclusive with workspaceId
+
+spec:
+  container:
+    image: registry.cn-hangzhou.aliyuncs.com/my-ns/my-agent:v1
+    # command: ["python", "app.py"]       # optional, overrides image CMD/ENTRYPOINT
+    # port: 9000                          # optional; spec.port below also works
+
+  # ───── resources ─────
+  cpu: 2                                  # default 2 cores
+  memory: 4096                            # default 4096 MB
+  # diskSize: 10240                       # optional, MB (10 GiB)
+
+  # ───── network (default PUBLIC; uncomment for VPC) ─────
+  # network:
+  #   mode: PUBLIC_AND_PRIVATE
+  #   vpcId: vpc-xxxxxxxx
+  #   vswitchIds: [vsw-xxxxxxxx]
+  #   securityGroupId: sg-xxxxxxxx
+
+  # ───── log to SLS (project + logstore must be set together) ─────
+  # log:
+  #   project: my-agent-logs
+  #   logstore: runtime
+
+  # ───── environment variables ─────
+  env:
+    LOG_LEVEL: info
+
+  # ───── endpoints (omit to auto-inject `default` / LATEST) ─────
+  endpoints:
+    - name: default
+      targetVersion: LATEST
+      # scaling:
+      #   minInstances: 1

docs/en/index.md

@@ -199,5 +199,5 @@ Errors are written to stderr as JSON:
 | `sandbox` | `sb` | Sandboxes plus file, process, context, template and browser sub-groups | [sandbox.md](./sandbox.md) |
 | `tool` |  | MCP and FunctionCall tools + sub-tool invocation | [tool.md](./tool.md) |
 | `skill` |  | Platform skill packages + local scan/load/exec | [skill.md](./skill.md) |
-| `runtime` | `rt` | Declarative Agent Runtime deploy (container mode) | [runtime.md](./runtime.md) |
+| `runtime` | `rt` | Declarative Agent Runtime deploy (container mode) | [runtime.md](./runtime.md) · [YAML reference](./runtime-yaml.md) |
 | `super-agent` | `sa` | Quickstart REPL, declarative deploy, CRUD, conversations | [super-agent.md](./super-agent.md) |