docs: make tutorials self-contained and document the current core API

.github/workflows/docs.yml

@@ -106,6 +106,8 @@ jobs:
         env:
           QITOS_DOCS_TOOLS: ${{ runner.temp }}/qitos-doc-tools
         run: |
+          python scripts/sync_tutorial_docs.py --check
+          python scripts/sync_api_reference.py --check
           python scripts/validate_docs.py
           node scripts/validate_docs_mdx.mjs
-          python -m pytest -q tests/test_tutorial_snippets.py tests/test_docs_golden_paths.py
+          python -m pytest -q tests/test_tutorial_snippets.py tests/test_docs_golden_paths.py tests/test_docs_page_execution.py

CHANGELOG.md

@@ -17,6 +17,12 @@ How to update:
 
 ## Unreleased
 
+### Added
+
+- Self-contained EN/zh notes-Agent lessons with complete inline files, source-synchronized excerpts, core API signatures and page-extracted installed-wheel checks.
+- Explicit serialized handoff lesson and documented same-head concurrent callback limitation; runtime unchanged.
+
+
 ### Fixed
 
 - Avoid reparsing unchanged journal bytes on each append/read while retaining full content hashing, external-write validation, crash recovery and durability checks.

README.md

@@ -14,7 +14,7 @@ Prototype methods, run benchmarks, and inspect long-horizon trajectories on one
 
 QitOS core is the small framework. Product-grade applications and showcase agents live in `qitos-zoo`, including planned apps such as `qitos-coder` and `qitos-cyber-agent`.
 
-[Quickstart](https://qitor.mintlify.app/quickstart) · [Tutorial Track](https://qitor.mintlify.app/tutorials) · [Benchmarks](https://qitor.mintlify.app/benchmarks/overview) · [CLI Reference](https://qitor.mintlify.app/reference/cli) · [Changelog](CHANGELOG.md) · [Chinese README](README.zh.md)
+[Quickstart](https://qitor.mintlify.app/quickstart) · [Tutorial Track](https://qitor.mintlify.app/tutorials/index) · [Benchmarks](https://qitor.mintlify.app/benchmarks/overview) · [CLI Reference](https://qitor.mintlify.app/reference/cli) · [Changelog](CHANGELOG.md) · [Chinese README](README.zh.md)
 
 ## What you can build
 
@@ -25,12 +25,15 @@ read-only qita. Framework correctness does not guarantee arbitrary model task su
 
 ## What's New
 
+- Self-contained web tutorials: complete notes-Agent code, bilingual learning path and source-checked core API reference; tests execute the files shown on each page.
+
+
 - Master fixes Python 3.10 publication, repeated journal parsing and portable historical evidence verification; these are separately tested successors to the historical G5 runtime.
 
 - G5 framework qualification passed; S4 local integration complete. Runtime identity: `717b4cf1b23f2ed252cd03234ffd8605038d9567`.
 - Bilingual docs converge on installation → project → configuration → Session → inspection → recovery/extension.
 - The default development branch is `master`, with CI/docs checks on pushes and PRs. Publication remains explicit.
-- Documentation/tutorial qualification is recorded separately. Remote synchronization is verified. Docs CI passed; successor CI stabilization is tracked with exact results in the [CI plan](docs/internal/plans/master_ci_stabilization.md). No package release or docs deployment was performed.
+- Documentation/tutorial qualification is recorded separately. Remote synchronization is verified. Docs CI passed; successor CI stabilization is tracked with exact results in the [CI plan](docs/internal/plans/master_ci_stabilization.md). Package releases and documentation deployments are tracked separately from CI qualification.
 
 ## Start developing
 

README.zh.md

@@ -25,6 +25,9 @@ store、sink 和 sandbox 可扩展；qita 只读检查 Trajectory。
 
 ## What's New
 
+- 网页自足教程：资料整理 Agent 的完整代码、中英文学习路径、可核对源码签名的核心 API Reference；测试直接执行网页文件。
+
+
 - master 修复 Python 3.10 publication、journal 重复解析和历史证据可移植核验；这些后继修复独立验证，不改写 G5 历史资格。
 - G5 框架资格通过，S4 本地集成完成，runtime 身份固定为 `717b4cf1b23f2ed252cd03234ffd8605038d9567`。
 - 双语文档统一到安装 → 项目 → 配置 → Session → 检查 → 恢复/扩展。

docs/AGENTS.md

@@ -18,3 +18,10 @@ This file never relaxes them and does not authorize plugins, deployments or mode
   compatibility, hard-thread-cancellation, automatic publication or lossless-redaction claim.
 - Use task-local pinned documentation dependencies. Run docs/tests/link/MDX checks
   and inspect actual desktop/mobile pages before promotion. No deployment is implied.
+
+- Core tutorials must contain all runnable files inline; links are optional conveniences.
+  Synchronize named excerpts and complete-file regions with scripts/sync_tutorial_docs.py.
+  CI uses --check and executes extracted EN/zh files from an installed wheel.
+- Keep docs/api-contracts.json explicit. Synchronize signatures with
+  scripts/sync_api_reference.py; every tutorial qitos import needs a reference entry.
+  Do not infer that submodule symbols are root-package exports.

docs/CONTRIBUTING.md

@@ -17,3 +17,13 @@ above historical records; preserve historical evidence and raw-log digests.
 Do not publish secrets, raw provider payloads or local paths. Remote branch
 sync, default-branch promotion, package release and docs deployment are separate
 operations requiring the applicable authorization.
+
+## Self-contained teaching pages
+
+Edit executable sources under `examples/tutorials/notes`, then synchronize with
+`python scripts/sync_tutorial_docs.py`. Every chapter includes all dependencies
+inline; source links are optional. API imports and source signatures are declared
+in `docs/api-contracts.json`; run `python scripts/sync_api_reference.py` in an
+environment with the matching QitOS installation. CI uses both scripts with
+`--check` and executes page-extracted files through `tests/test_docs_page_execution.py`.
+Maintain EN/zh prose together; do not translate executable identifiers or defaults.

docs/README.md

@@ -21,3 +21,13 @@ in the promotion ledger; change them deliberately after verification.
 Inspect both languages for introduction, Quickstart, Session, multi-agent,
 sandbox, qita and configuration, including a narrow mobile viewport.
 This is local preview only; this task does not deploy the documentation site.
+
+## Self-contained teaching pages
+
+Edit executable sources under `examples/tutorials/notes`, then synchronize with
+`python scripts/sync_tutorial_docs.py`. Every chapter includes all dependencies
+inline; source links are optional. API imports and source signatures are declared
+in `docs/api-contracts.json`; run `python scripts/sync_api_reference.py` in an
+environment with the matching QitOS installation. CI uses both scripts with
+`--check` and executes page-extracted files through `tests/test_docs_page_execution.py`.
+Maintain EN/zh prose together; do not translate executable identifiers or defaults.