diff --git a/.agents/docs/2026-10-24-template-readiness.md b/.agents/docs/2026-10-24-template-readiness.md
new file mode 100644
index 0000000..09ce2ec
--- /dev/null
+++ b/.agents/docs/2026-10-24-template-readiness.md
@@ -0,0 +1,9 @@
+# Runnable template and native CI checkpoint
+
+The default greeter template uses the upstream grpc namespace/API and generates a real service through the package-provided host plugin/rule. Both GCC 16 and LLVM 23 actual mcpp new consumers passed a loopback RPC plus the failure path. Template CI on source 839b61e passed; its Linux/macOS native workflow subsequently completed the advanced program but failed a stale generated-file assertion.
+
+Current mcpp places generated files under an invocation/project directory. CI now checks common/types.pb.cc beside the actual orders_mock.grpc.pb.h instead of assuming target/.build-mcpp/out/common. It locates the Ninja graph by the generation edge rather than relying on filesystem order, which can select a host-tool graph. Local LLVM 23.1.3 mcpp run on examples/advanced passed in 3m40s; the produced nonempty shared-proto source, mock header and GENERATE edge descriptions were checked.
+
+The pinned mcpp 2026.10.24.1 includes the object-layout cache fix for which the old MCPP_BUILD_CACHE=local workaround was added. Dropping that expired workaround lets sibling consumers reuse SDK objects; all examples still build and execute their generated code. Native source CI must revalidate the new checkpoint. Windows runtime remains unavailable with the declared OpenSSL provider; plugin/rule host-tool availability is tested separately through the index.
+
+Root READMEs use the common concise style (52 lines per language); prior detailed guidance is under docs/. Package/runtime/plugin/rule versions stay coupled at 1.83.0.1. No merge, tag or release is included.
diff --git a/.agents/docs/2026-10-25-unified-mwrap-checkpoint.md b/.agents/docs/2026-10-25-unified-mwrap-checkpoint.md
new file mode 100644
index 0000000..f451119
--- /dev/null
+++ b/.agents/docs/2026-10-25-unified-mwrap-checkpoint.md
@@ -0,0 +1,8 @@
+# Unified mwrap first release
+
+Package/module: `mcpplibs.mwrap.grpc`; upstream version: `1.83.0`.
+
+This checkpoint migrates wrapper identity while retaining upstream API names and SDK sources.
+Default README is English with a mandatory Chinese counterpart; original section order is preserved.
+Validation and release evidence are recorded in the PR and the index ecosystem ledger.
+No old release tag or source resource is rewritten.
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..8a6c241
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+# Preserve upstream document bytes and original whitespace on every platform.
+upstream/** -text -whitespace
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 421dd21..a06165c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,8 +1,8 @@
 name: CI
 
-# Docs carry no build risk, and this workflow's linux leg is a ~2h serial
-# gRPC build (see timeout-minutes below) — a markdown-only change would spend
-# it twice, once on the PR and once again on main. `paths-ignore` on both
+# The native leg builds gRPC and runs several generated-code consumers;
+# a markdown-only change would spend that time twice, once on the PR and
+# once again on main. `paths-ignore` on both
 # triggers, not just the PR one, or the merge pays the second half anyway.
 #
 # Deliberately NOT ignored: mcpp.toml, build.mcpp, templates/, examples/,
@@ -29,25 +29,15 @@ env:
   #               and `rerun_if_changed_glob`, without which generate_all()
   #               would not re-run when a .proto is ADDED (no declared file's
   #               hash changes), silently never generating it
-  MCPP_VERSION: "2026.8.6.2"
+  MCPP_VERSION: "2026.10.24.1"
 
 jobs:
   build:
     name: ${{ matrix.name }}
     runs-on: ${{ matrix.os }}
-    # Every example is its own project depending on `grpc` by path, and each
-    # one builds gRPC from source again — the cache does not carry across
-    # them. Measured on linux: module test 25min, then ~31min per example.
-    # Three examples already sat at ~90min under the old 120 cap; adding
-    # `advanced` pushed the run past it and the job was cancelled mid-build,
-    # which reads like a failure and is not one.
-    #
-    # Raising the cap is the honest short-term answer, not the right one:
-    # what actually costs the hour and a half is rebuilding the same gRPC
-    # four times in series. Splitting the examples into their own matrix leg
-    # (or getting the dependency cache to hit across sibling projects) turns
-    # ~2h of wall clock into ~35min. Worth doing on its own, not inside a
-    # release PR.
+    # Allow a cold native build plus all generated-code consumers. The pinned
+    # client can reuse SDK objects across projects; the former local-cache
+    # workaround forced four cold builds and is no longer needed.
     timeout-minutes: 210
     strategy:
       fail-fast: false
@@ -64,6 +54,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Mwrap identity and bilingual README contract
+        run: python3 tools/check_mwrap_release.py
+
       - name: Download pinned mcpp
         shell: bash
         run: |
@@ -89,17 +82,13 @@ jobs:
         run: |
           "$MCPP" index update
 
-      # mcpp#344: object-path disambiguation keys on basename collisions across
-      # the whole build dir, while the package cache key covers only the
-      # dependency — one entry can hold two layouts. This graph has several
-      # colliding basenames (abseil/protobuf `parser.cc`, abseil/gRPC
-      # `status.cc`, `time.cc`), so the package cache is bypassed exactly as
-      # mcpp-index's own CI does. Drop this once the pin reaches 2026.8.3.4.
+      # The pinned client includes the object-layout cache fix (2026.8.3.4).
+      # Reuse SDK objects between actual consumers; every example still builds
+      # its own generated sources and executes its runtime checks.
       - name: Build the library and run the module test
         shell: bash
         env:
           MCPP_INDEX_MIRROR: GLOBAL
-          MCPP_BUILD_CACHE: local
         run: |
           "$MCPP" --version
           "$MCPP" test
@@ -110,7 +99,6 @@ jobs:
         working-directory: examples/helloworld
         env:
           MCPP_INDEX_MIRROR: GLOBAL
-          MCPP_BUILD_CACHE: local
         run: |
           "$MCPP" run
 
@@ -124,7 +112,6 @@ jobs:
         working-directory: examples/greeter
         env:
           MCPP_INDEX_MIRROR: GLOBAL
-          MCPP_BUILD_CACHE: local
         run: |
           "$MCPP" run
 
@@ -138,7 +125,6 @@ jobs:
         working-directory: examples/advanced
         env:
           MCPP_INDEX_MIRROR: GLOBAL
-          MCPP_BUILD_CACHE: local
         run: |
           "$MCPP" run
           # The mock header is declared by the edge and produced by protoc;
@@ -148,20 +134,20 @@ jobs:
           test -n "$out" || { echo "no mock header produced"; exit 1; }
           echo "mock header: $out"
           # The shared tree was generated, not just searched.
-          test -f target/.build-mcpp/out/common/types.pb.cc \
+          test -s "$(dirname "$out")/common/types.pb.cc" \
             || { echo "shared-proto was not generated"; exit 1; }
           # The edge describes ITSELF. This is the rule's half of observability
           # — mcpp already puts the full argv in build.ninja, so what the rule
           # owns is "which knobs produced it", and that string is what every
           # build prints. Asserting it keeps the two from drifting apart.
-          nj=$(find target -name build.ninja | head -1)
-          grep -q 'description = GENERATE protoc:orders (+grpc +mock,' "$nj" \
-            || { echo "edge description does not describe its knobs:";
-                 grep -o 'description = GENERATE protoc:.*' "$nj"; exit 1; }
+          nj=$(find target -name build.ninja -exec grep -lF \
+            'description = GENERATE protoc:orders (+grpc +mock,' {} + | head -1)
+          test -n "$nj" \
+            || { echo "no build graph describes the requested generation knobs"; exit 1; }
           grep -o 'description = GENERATE protoc:.*' "$nj"
 
   package-versions-match:
-    name: all three packages share one version
+    name: runtime and host tools share upstream source
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -174,14 +160,17 @@ jobs:
       - name: versions must match
         shell: bash
         run: |
-          lib=$(awk -F'"' '/^version/{print $2; exit}' mcpp.toml)
-          plug=$(awk -F'"' '/^version/{print $2; exit}' plugin/mcpp.toml)
-          rule=$(awk -F'"' '/^version/{print $2; exit}' rules/mcpp.toml)
-          echo "grpc=$lib  grpc-plugin=$plug  grpcgen=$rule"
-          rc=0
-          [ "$lib" = "$plug" ] || { echo "FAIL: grpc-plugin ($plug) != grpc ($lib)"; rc=1; }
-          [ "$lib" = "$rule" ] || { echo "FAIL: grpcgen ($rule) != grpc ($lib)"; rc=1; }
-          exit $rc
+          python3 - <<'PYVERS'
+          import tomllib
+          from pathlib import Path
+          runtime = tomllib.loads(Path("mcpp.toml").read_text())["package"]
+          plugin = tomllib.loads(Path("plugin/mcpp.toml").read_text())["package"]
+          rule = tomllib.loads(Path("rules/mcpp.toml").read_text())["package"]
+          upstream = runtime["metadata"]["mwrap"]["upstream-version"]
+          assert runtime["version"] == upstream == "1.83.0"
+          assert plugin["version"] == rule["version"] == upstream + ".1"
+          print("runtime", runtime["version"], "host tools", plugin["version"], "same pinned source")
+          PYVERS
 
       # rules/mcpp.toml states that the package name and the module name are
       # kept EQUAL, and that this is what makes the package work on every
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..f0c6447
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,49 @@
+name: Release
+on:
+  push:
+    tags: ["mwrap-*"]
+permissions:
+  contents: read
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      actions: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag, upstream version and bilingual entry pages
+        run: python3 tools/check_mwrap_release.py --tag "$GITHUB_REF_NAME"
+      - name: Require successful source CI at this exact commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          result=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow ci.yml --commit "$GITHUB_SHA" --limit 1 --json status,conclusion --jq '.[0] | .status == "completed" and .conclusion == "success"')
+          test "$result" = true || { echo 'No successful source CI at the tag commit'; exit 1; }
+      - name: Build immutable source asset and publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#mwrap-}"
+          repo="${GITHUB_REPOSITORY#*/}"
+          asset="${repo}-${version}.tar.gz"
+          git archive --format=tar.gz --prefix="${repo}-${version}/" "$GITHUB_SHA" > "$RUNNER_TEMP/$asset"
+          (cd "$RUNNER_TEMP" && sha256sum "$asset" > "$asset.sha256")
+          if gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            echo 'Release already exists; refusing to change immutable assets'; exit 1
+          fi
+          extra=()
+          if [[ "$version" == *-rc* ]]; then extra+=(--prerelease); fi
+          gh release create "$GITHUB_REF_NAME" "$RUNNER_TEMP/$asset" "$RUNNER_TEMP/$asset.sha256" \
+            --repo "$GITHUB_REPOSITORY" --verify-tag --title "$repo $version" \
+            --notes "Module wrapper for upstream $version. New mwrap package identities become installable after mcpp-index publication; see the bilingual README for the tested support scope." "${extra[@]}"
diff --git a/.github/workflows/templates.yml b/.github/workflows/templates.yml
new file mode 100644
index 0000000..5b5c575
--- /dev/null
+++ b/.github/workflows/templates.yml
@@ -0,0 +1,42 @@
+name: Actual project templates
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: templates-${{ github.ref }}
+  cancel-in-progress: true
+env:
+  MCPP_VERSION: "2026.10.24.1"
+jobs:
+  templates:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: ~/.mcpp/registry
+          key: template-registry-${{ github.repository }}-${{ env.MCPP_VERSION }}-${{ hashFiles('mcpp.toml') }}
+          restore-keys: |
+            template-registry-${{ github.repository }}-${{ env.MCPP_VERSION }}-
+      - name: Install current mcpp
+        shell: bash
+        run: |
+          archive="mcpp-${MCPP_VERSION}-linux-x86_64.tar.gz"
+          curl -L -fsS -o "$archive" "https://github.com/mcpp-community/mcpp/releases/download/v${MCPP_VERSION}/$archive"
+          tar -xzf "$archive"
+          root="$PWD/mcpp-${MCPP_VERSION}-linux-x86_64"
+          mkdir -p "$HOME/.mcpp/registry"
+          cp -a "$root/registry/." "$HOME/.mcpp/registry/"
+          echo "$root/bin" >> "$GITHUB_PATH"
+      - name: Install toolchains
+        run: |
+          mcpp toolchain install gcc 16.1.0
+          mcpp toolchain install llvm 23.1.3
+      - name: Actual scaffold, strict build and runtime behavior
+        run: |
+          python3 tools/test_template.py --toolchain llvm@23.1.3 --namespace grpc
diff --git a/.gitignore b/.gitignore
index 8fcdb24..62e3140 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@ target/
 .mcpp/
 mcpp.lock
 compile_commands.json
+
+.xlings/
diff --git a/.xlings.json b/.xlings.json
new file mode 100644
index 0000000..4dcdd6b
--- /dev/null
+++ b/.xlings.json
@@ -0,0 +1,5 @@
+{
+  "workspace": {
+    "xim:mcpp": "2026.10.24.1"
+  }
+}
diff --git a/LICENSE b/LICENSE
index 9835265..d645695 100644
--- a/LICENSE
+++ b/LICENSE
@@ -200,424 +200,3 @@
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-
------------------------------------------------------------
-
-Following applies to:
-./src/objective-c/!ProtoCompiler-gRPCCppPlugin.podspec
-./src/objective-c/!ProtoCompiler-gRPCPlugin.podspec
-./src/objective-c/!ProtoCompiler.podspec
-./src/objective-c/BoringSSL-GRPC.podspec
-./templates/src/objective-c/!ProtoCompiler-gRPCCppPlugin.podspec.inja
-./templates/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec.inja
-./templates/src/objective-c/!ProtoCompiler.podspec.inja
-./templates/src/objective-c/BoringSSL-GRPC.podspec.template
-
-BSD 3-Clause License
-
-Copyright 2016, Google Inc.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice,
-this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-this list of conditions and the following disclaimer in the documentation
-and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-contributors may be used to endorse or promote products derived from this
-software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-THE POSSIBILITY OF SUCH DAMAGE.
-
------------------------------------------------------------
-
-Following applies to:
-./etc/roots.pem
-
-Mozilla Public License Version 2.0
-==================================
-
-1. Definitions
---------------
-
-1.1. "Contributor"
-    means each individual or legal entity that creates, contributes to
-    the creation of, or owns Covered Software.
-
-1.2. "Contributor Version"
-    means the combination of the Contributions of others (if any) used
-    by a Contributor and that particular Contributor's Contribution.
-
-1.3. "Contribution"
-    means Covered Software of a particular Contributor.
-
-1.4. "Covered Software"
-    means Source Code Form to which the initial Contributor has attached
-    the notice in Exhibit A, the Executable Form of such Source Code
-    Form, and Modifications of such Source Code Form, in each case
-    including portions thereof.
-
-1.5. "Incompatible With Secondary Licenses"
-    means
-
-    (a) that the initial Contributor has attached the notice described
-        in Exhibit B to the Covered Software; or
-
-    (b) that the Covered Software was made available under the terms of
-        version 1.1 or earlier of the License, but not also under the
-        terms of a Secondary License.
-
-1.6. "Executable Form"
-    means any form of the work other than Source Code Form.
-
-1.7. "Larger Work"
-    means a work that combines Covered Software with other material, in 
-    a separate file or files, that is not Covered Software.
-
-1.8. "License"
-    means this document.
-
-1.9. "Licensable"
-    means having the right to grant, to the maximum extent possible,
-    whether at the time of the initial grant or subsequently, any and
-    all of the rights conveyed by this License.
-
-1.10. "Modifications"
-    means any of the following:
-
-    (a) any file in Source Code Form that results from an addition to,
-        deletion from, or modification of the contents of Covered
-        Software; or
-
-    (b) any new file in Source Code Form that contains any Covered
-        Software.
-
-1.11. "Patent Claims" of a Contributor
-    means any patent claim(s), including without limitation, method,
-    process, and apparatus claims, in any patent Licensable by such
-    Contributor that would be infringed, but for the grant of the
-    License, by the making, using, selling, offering for sale, having
-    made, import, or transfer of either its Contributions or its
-    Contributor Version.
-
-1.12. "Secondary License"
-    means either the GNU General Public License, Version 2.0, the GNU
-    Lesser General Public License, Version 2.1, the GNU Affero General
-    Public License, Version 3.0, or any later versions of those
-    licenses.
-
-1.13. "Source Code Form"
-    means the form of the work preferred for making modifications.
-
-1.14. "You" (or "Your")
-    means an individual or a legal entity exercising rights under this
-    License. For legal entities, "You" includes any entity that
-    controls, is controlled by, or is under common control with You. For
-    purposes of this definition, "control" means (a) the power, direct
-    or indirect, to cause the direction or management of such entity,
-    whether by contract or otherwise, or (b) ownership of more than
-    fifty percent (50%) of the outstanding shares or beneficial
-    ownership of such entity.
-
-2. License Grants and Conditions
---------------------------------
-
-2.1. Grants
-
-Each Contributor hereby grants You a world-wide, royalty-free,
-non-exclusive license:
-
-(a) under intellectual property rights (other than patent or trademark)
-    Licensable by such Contributor to use, reproduce, make available,
-    modify, display, perform, distribute, and otherwise exploit its
-    Contributions, either on an unmodified basis, with Modifications, or
-    as part of a Larger Work; and
-
-(b) under Patent Claims of such Contributor to make, use, sell, offer
-    for sale, have made, import, and otherwise transfer either its
-    Contributions or its Contributor Version.
-
-2.2. Effective Date
-
-The licenses granted in Section 2.1 with respect to any Contribution
-become effective for each Contribution on the date the Contributor first
-distributes such Contribution.
-
-2.3. Limitations on Grant Scope
-
-The licenses granted in this Section 2 are the only rights granted under
-this License. No additional rights or licenses will be implied from the
-distribution or licensing of Covered Software under this License.
-Notwithstanding Section 2.1(b) above, no patent license is granted by a
-Contributor:
-
-(a) for any code that a Contributor has removed from Covered Software;
-    or
-
-(b) for infringements caused by: (i) Your and any other third party's
-    modifications of Covered Software, or (ii) the combination of its
-    Contributions with other software (except as part of its Contributor
-    Version); or
-
-(c) under Patent Claims infringed by Covered Software in the absence of
-    its Contributions.
-
-This License does not grant any rights in the trademarks, service marks,
-or logos of any Contributor (except as may be necessary to comply with
-the notice requirements in Section 3.4).
-
-2.4. Subsequent Licenses
-
-No Contributor makes additional grants as a result of Your choice to
-distribute the Covered Software under a subsequent version of this
-License (see Section 10.2) or under the terms of a Secondary License (if
-permitted under the terms of Section 3.3).
-
-2.5. Representation
-
-Each Contributor represents that the Contributor believes its
-Contributions are its original creation(s) or it has sufficient rights
-to grant the rights to its Contributions conveyed by this License.
-
-2.6. Fair Use
-
-This License is not intended to limit any rights You have under
-applicable copyright doctrines of fair use, fair dealing, or other
-equivalents.
-
-2.7. Conditions
-
-Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
-in Section 2.1.
-
-3. Responsibilities
--------------------
-
-3.1. Distribution of Source Form
-
-All distribution of Covered Software in Source Code Form, including any
-Modifications that You create or to which You contribute, must be under
-the terms of this License. You must inform recipients that the Source
-Code Form of the Covered Software is governed by the terms of this
-License, and how they can obtain a copy of this License. You may not
-attempt to alter or restrict the recipients' rights in the Source Code
-Form.
-
-3.2. Distribution of Executable Form
-
-If You distribute Covered Software in Executable Form then:
-
-(a) such Covered Software must also be made available in Source Code
-    Form, as described in Section 3.1, and You must inform recipients of
-    the Executable Form how they can obtain a copy of such Source Code
-    Form by reasonable means in a timely manner, at a charge no more
-    than the cost of distribution to the recipient; and
-
-(b) You may distribute such Executable Form under the terms of this
-    License, or sublicense it under different terms, provided that the
-    license for the Executable Form does not attempt to limit or alter
-    the recipients' rights in the Source Code Form under this License.
-
-3.3. Distribution of a Larger Work
-
-You may create and distribute a Larger Work under terms of Your choice,
-provided that You also comply with the requirements of this License for
-the Covered Software. If the Larger Work is a combination of Covered
-Software with a work governed by one or more Secondary Licenses, and the
-Covered Software is not Incompatible With Secondary Licenses, this
-License permits You to additionally distribute such Covered Software
-under the terms of such Secondary License(s), so that the recipient of
-the Larger Work may, at their option, further distribute the Covered
-Software under the terms of either this License or such Secondary
-License(s).
-
-3.4. Notices
-
-You may not remove or alter the substance of any license notices
-(including copyright notices, patent notices, disclaimers of warranty,
-or limitations of liability) contained within the Source Code Form of
-the Covered Software, except that You may alter any license notices to
-the extent required to remedy known factual inaccuracies.
-
-3.5. Application of Additional Terms
-
-You may choose to offer, and to charge a fee for, warranty, support,
-indemnity or liability obligations to one or more recipients of Covered
-Software. However, You may do so only on Your own behalf, and not on
-behalf of any Contributor. You must make it absolutely clear that any
-such warranty, support, indemnity, or liability obligation is offered by
-You alone, and You hereby agree to indemnify every Contributor for any
-liability incurred by such Contributor as a result of warranty, support,
-indemnity or liability terms You offer. You may include additional
-disclaimers of warranty and limitations of liability specific to any
-jurisdiction.
-
-4. Inability to Comply Due to Statute or Regulation
----------------------------------------------------
-
-If it is impossible for You to comply with any of the terms of this
-License with respect to some or all of the Covered Software due to
-statute, judicial order, or regulation then You must: (a) comply with
-the terms of this License to the maximum extent possible; and (b)
-describe the limitations and the code they affect. Such description must
-be placed in a text file included with all distributions of the Covered
-Software under this License. Except to the extent prohibited by statute
-or regulation, such description must be sufficiently detailed for a
-recipient of ordinary skill to be able to understand it.
-
-5. Termination
---------------
-
-5.1. The rights granted under this License will terminate automatically
-if You fail to comply with any of its terms. However, if You become
-compliant, then the rights granted under this License from a particular
-Contributor are reinstated (a) provisionally, unless and until such
-Contributor explicitly and finally terminates Your grants, and (b) on an
-ongoing basis, if such Contributor fails to notify You of the
-non-compliance by some reasonable means prior to 60 days after You have
-come back into compliance. Moreover, Your grants from a particular
-Contributor are reinstated on an ongoing basis if such Contributor
-notifies You of the non-compliance by some reasonable means, this is the
-first time You have received notice of non-compliance with this License
-from such Contributor, and You become compliant prior to 30 days after
-Your receipt of the notice.
-
-5.2. If You initiate litigation against any entity by asserting a patent
-infringement claim (excluding declaratory judgment actions,
-counter-claims, and cross-claims) alleging that a Contributor Version
-directly or indirectly infringes any patent, then the rights granted to
-You by any and all Contributors for the Covered Software under Section
-2.1 of this License shall terminate.
-
-5.3. In the event of termination under Sections 5.1 or 5.2 above, all
-end user license agreements (excluding distributors and resellers) which
-have been validly granted by You or Your distributors under this License
-prior to termination shall survive termination.
-
-************************************************************************
-*                                                                      *
-*  6. Disclaimer of Warranty                                           *
-*  -------------------------                                           *
-*                                                                      *
-*  Covered Software is provided under this License on an "as is"       *
-*  basis, without warranty of any kind, either expressed, implied, or  *
-*  statutory, including, without limitation, warranties that the       *
-*  Covered Software is free of defects, merchantable, fit for a        *
-*  particular purpose or non-infringing. The entire risk as to the     *
-*  quality and performance of the Covered Software is with You.        *
-*  Should any Covered Software prove defective in any respect, You     *
-*  (not any Contributor) assume the cost of any necessary servicing,   *
-*  repair, or correction. This disclaimer of warranty constitutes an   *
-*  essential part of this License. No use of any Covered Software is   *
-*  authorized under this License except under this disclaimer.         *
-*                                                                      *
-************************************************************************
-
-************************************************************************
-*                                                                      *
-*  7. Limitation of Liability                                          *
-*  --------------------------                                          *
-*                                                                      *
-*  Under no circumstances and under no legal theory, whether tort      *
-*  (including negligence), contract, or otherwise, shall any           *
-*  Contributor, or anyone who distributes Covered Software as          *
-*  permitted above, be liable to You for any direct, indirect,         *
-*  special, incidental, or consequential damages of any character      *
-*  including, without limitation, damages for lost profits, loss of    *
-*  goodwill, work stoppage, computer failure or malfunction, or any    *
-*  and all other commercial damages or losses, even if such party      *
-*  shall have been informed of the possibility of such damages. This   *
-*  limitation of liability shall not apply to liability for death or   *
-*  personal injury resulting from such party's negligence to the       *
-*  extent applicable law prohibits such limitation. Some               *
-*  jurisdictions do not allow the exclusion or limitation of           *
-*  incidental or consequential damages, so this exclusion and          *
-*  limitation may not apply to You.                                    *
-*                                                                      *
-************************************************************************
-
-8. Litigation
--------------
-
-Any litigation relating to this License may be brought only in the
-courts of a jurisdiction where the defendant maintains its principal
-place of business and such litigation shall be governed by laws of that
-jurisdiction, without reference to its conflict-of-law provisions.
-Nothing in this Section shall prevent a party's ability to bring
-cross-claims or counter-claims.
-
-9. Miscellaneous
-----------------
-
-This License represents the complete agreement concerning the subject
-matter hereof. If any provision of this License is held to be
-unenforceable, such provision shall be reformed only to the extent
-necessary to make it enforceable. Any law or regulation which provides
-that the language of a contract shall be construed against the drafter
-shall not be used to construe this License against a Contributor.
-
-10. Versions of the License
----------------------------
-
-10.1. New Versions
-
-Mozilla Foundation is the license steward. Except as provided in Section
-10.3, no one other than the license steward has the right to modify or
-publish new versions of this License. Each version will be given a
-distinguishing version number.
-
-10.2. Effect of New Versions
-
-You may distribute the Covered Software under the terms of the version
-of the License under which You originally received the Covered Software,
-or under the terms of any subsequent version published by the license
-steward.
-
-10.3. Modified Versions
-
-If you create software not governed by this License, and you want to
-create a new license for such software, you may create and use a
-modified version of this License if you rename the license and remove
-any references to the name of the license steward (except to note that
-such modified license differs from this License).
-
-10.4. Distributing Source Code Form that is Incompatible With Secondary
-Licenses
-
-If You choose to distribute Source Code Form that is Incompatible With
-Secondary Licenses under the terms of this version of the License, the
-notice described in Exhibit B of this License must be attached.
-
-Exhibit A - Source Code Form License Notice
--------------------------------------------
-
-  This Source Code Form is subject to the terms of the Mozilla Public
-  License, v. 2.0. If a copy of the MPL was not distributed with this
-  file, You can obtain one at http://mozilla.org/MPL/2.0/.
-
-If it is not possible or desirable to put the notice in a particular
-file, then You may include the notice in a location (such as a LICENSE
-file in a relevant directory) where a recipient would be likely to look
-for such a notice.
-
-You may add additional accurate notices of copyright ownership.
-
-Exhibit B - "Incompatible With Secondary Licenses" Notice
----------------------------------------------------------
-
-  This Source Code Form is "Incompatible With Secondary Licenses", as
-  defined by the Mozilla Public License, v. 2.0.
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..a50ca9d
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,8 @@
+grpc-m: C++ module wrapper
+Copyright (c) 2026 mcpp-community contributors
+
+The wrapper contributions are licensed under the Apache License, Version 2.0.
+Upstream code, copied interfaces, generated bindings and dependencies retain
+their original licenses and copyright notices. Original upstream README and
+license documents are retained in upstream/grpc/; provenance and checksums
+are recorded in upstream/documents.json.
diff --git a/README.md b/README.md
index c2001df..6b3046c 100644
--- a/README.md
+++ b/README.md
@@ -1,248 +1,77 @@
 # grpc-m
 
-> gRPC 1.83.0 for mcpp — built from upstream source, `import grpc;` ready, one command to a working RPC
+> gRPC 1.83.0 from source, preserving grpc:: and sharing indexed dependencies.
+
+**English** · [简体中文](README.zh.md) · [Upstream](https://github.com/grpc/grpc) · [Releases](https://github.com/mcpplibs/grpc-m/releases) · [mcpp](https://github.com/mcpp-community/mcpp) · [Index](https://github.com/mcpplibs/mcpp-index)
 
-[![Release](https://img.shields.io/github/v/release/mcpplibs/grpc-m)](https://github.com/mcpplibs/grpc-m/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
-[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
-[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![gRPC 1.83.0](https://img.shields.io/badge/gRPC-1.83.0-brightgreen.svg)](https://github.com/grpc/grpc/releases/tag/v1.83.0)
+[![License](https://img.shields.io/badge/license-Apache-2.0-blue.svg)](LICENSE)
+[![mcpp-community](https://img.shields.io/badge/mcpp--community-mwrap-blue)](https://github.com/mcpp-community)
+[![CI](https://github.com/mcpplibs/grpc-m/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpplibs/grpc-m/actions/workflows/ci.yml)
+
+## Modules
 
-| English - [简体中文](README.zh.md) |
-|:---:|
-| [mcpp build tool](https://github.com/mcpp-community/mcpp) · [package index](https://github.com/mcpplibs/mcpp-index) · [Issues](https://github.com/mcpplibs/grpc-m/issues) |
+- `import mcpplibs.mwrap.grpc;`: grpc:: client/server and status APIs
+- `import mcpplibs.mwrap.grpc.macros;`: Version macro mappings
 
-`grpc-m` builds gRPC's C++ stack from upstream source with **zero patches**, and takes
-abseil, protobuf, re2, c-ares, OpenSSL and zlib from
-[mcpp-index](https://github.com/mcpplibs/mcpp-index) rather than vendoring a second copy
-of each. No CMake, no Bazel, no configure step — `mcpp build` is the whole story.
+> More Modules API -> [Usage and API](docs/usage.md)
 
 ## Quick Start
 
-```bash
-mcpp new mygreeter --template grpc && cd mygreeter
+```sh
+mcpp new greeter --template mcpplibs.mwrap.grpc@1.83.0
+cd greeter
 mcpp run
 ```
 
-```
-server listening on 127.0.0.1:34733
-Greeter replied: Hello mcpp
-```
-
-Or add it to an existing project:
-
-```bash
-mcpp add grpc.grpc
-```
-
 ```toml
-[dependencies.grpc]
-grpc = "1.83.0"
+[dependencies]
+mcpplibs.mwrap.grpc = { version = "1.83.0", features = ["codegen"] }
 ```
 
 ## Two ways to use it
 
-gRPC's code generator emits **headers**, so any real program includes protoc output. The
-module is the ergonomic surface for everything you write by hand around it.
-
 ```cpp
-#include <string>                     // std headers first
-#include "helloworld.grpc.pb.h"       // then protoc output
-import grpc;                          // the module LAST — see below
-
-class Greeter final : public helloworld::Greeter::Service {
-    grpc::Status SayHello(grpc::ServerContext*, const helloworld::HelloRequest* req,
-                          helloworld::HelloReply* rep) override {
-        rep->set_message("Hello " + req->name());
-        return grpc::Status::OK;
-    }
-};
-```
-
-> **`import grpc;` goes last.** The module carries the standard library in its BMI (it
-> wraps `<grpcpp/grpcpp.h>`, which pulls in most of it), so a textual `#include` *after*
-> the import delivers a second copy and the build fails — `redefinition of
-> std::__is_constant_evaluated`, or `ambiguous overload for operator==` on `std::string`.
-> Put every `#include` above the import and everything resolves: the exported entities
-> belong to the **global module**, so the textual and imported views are the same
-> entities. Verified both ways round with gcc 16.1.0.
-
-Prefer plain headers instead? That works too and needs no import at all:
-
-```cpp
-#include <grpcpp/grpcpp.h>
 #include "helloworld.grpc.pb.h"
+import mcpplibs.mwrap.grpc;
 ```
 
-## Code generation
-
-gRPC needs two host tools — `protoc` and `grpc_cpp_plugin` — and since **mcpp 2026.8.5.1**
-you no longer supply them yourself. Declare them on the dependencies they belong to, add
-the codegen rule, and that is the entire setup:
-
-```toml
-[dependencies.grpc]
-grpc = { version = "1.83.0", features = ["codegen"] }
-```
-
-```cpp
-// build.mcpp — in full
-import mcpp;
-import grpcgen;
-int main() { return grpcgen::generate_all() ? 0 : 1; }
-```
-
-One dependency and one line. Which tools gRPC codegen needs — protoc, the C++
-plugin, the rule that drives them — is this package's knowledge, and
-`features = ["codegen"]` is where it says so. Adding a `.proto` means dropping
-a file in `proto/`; there is no list to keep in sync.
+Include standard/generated headers before imports. Plain `<grpcpp/grpcpp.h>` also works.
+`.macros` maps version constants; preprocessing macros remain textual.
 
-That is `templates/greeter`, and `mcpp new --template grpc` gives it to you ready to
-build (`--template` takes the PACKAGE; spell the template out as `grpc:greeter` when a
-package ships more than one). **No generated file is checked in any more** — edit the `.proto` and rebuild.
+## Code generation
 
-`grpcgen` is an ordinary mcpp package holding the rule, written in C++ and versioned
-alongside gRPC. Rules ship through the package manager you already have, so there is no
-second language here the way xmake has Lua rules and Bazel has Starlark. It needs
-**mcpp 2026.8.6.2** — 2026.8.5.2 is where a rule package first became able to use `import std;`
-and `import mcpp;`.
+`codegen` supplies protoc, grpc_cpp_plugin and the host rule; the default template generates its stubs.
+[Rule API and generated-header ordering](docs/usage.md)
 
 ## When you need more control
 
-Past `generate_all()` there is no cliff — each layer is the next one's
-**defaults, not another road**: `generate_all(opt)` *is* `submit(plan_all(opt))`,
-and `.grpc = true` *is* `.plugins = {cpp()}`.
-
-```cpp
-// L1 — declarative knobs
-grpcgen::generate_all({
-    .extra_dirs  = {"../shared-proto"},   // shared .proto tree, generated too
-    .imports     = {"/opt/googleapis"},   // search only, not generated
-    .mock        = true,                  // gRPC's generate_mock_code=true
-    .protoc_args = {"--experimental_allow_proto3_optional"},
-});
-
-// L2 — the plugin list; `.grpc = true` is sugar for "cpp() is in it"
-grpcgen::generate_all({ .plugins = { grpcgen::cpp(), my_plugin } });
-
-// L3 — plan / submit: no requirement is exotic enough to need bypassing the rule
-auto edges = grpcgen::plan_all();
-for (auto& e : edges) e.arg("--whatever");
-grpcgen::submit(edges);
-```
-
-`extra_dirs` vs `imports` is not a pedantic distinction: protoc writes
-`#include "common/types.pb.h"` into every file that imports that .proto, so a
-shared tree reached only through `-I` yields a header **nobody produced**, and
-the failure surfaces far from its cause. Use `extra_dirs` when that code is
-yours to build; `imports` when it comes from somewhere you already link.
-
-**Observability, and whose job it is**: mcpp writes each edge's full argv into
-`build.ninja` — `ninja -t commands <output>` recovers it, and the rule does not
-duplicate that. What the rule owns is *which knobs* produced the command, and it
-puts that in the description every build prints:
-
-```
-GENERATE protoc:orders (+grpc +mock, -Iproto -I../shared-proto)
-```
-
-`examples/advanced` covers L1 + L3.
-
-Three examples, on purpose:
-
-| | |
-|---|---|
-| `examples/greeter` | the template instantiated — 3-line `build.mcpp` via `grpcgen` |
-| `examples/helloworld` | the same program with the rule written out by hand, so the mechanism stays legible |
-| `examples/advanced` | the layered knobs: a shared .proto tree generated across roots, gRPC mocks, and plan/submit with an assertion in between |
-
-Three properties this buys, none of which hand-managed codegen can offer:
-
-- **A version mismatch is not expressible.** A tool's version *is* its dependency's
-  version, so a `protoc` that disagrees with the protobuf runtime — a **runtime** failure,
-  and the nastiest thing about protobuf codegen — cannot happen. (Conan needed a
-  `<host_version>` placeholder to approximate this; protobuf's own CMake still has an open
-  issue where `Protobuf_PROTOC_EXECUTABLE` is ignored in CONFIG mode.)
-- **Incremental.** Generation is a ninja edge, so it re-runs when its `.proto` changes and
-  not otherwise.
-- **Cross-compilation is correct by construction.** Under `--target` the tools are still
-  built for the build machine, with no action from you.
-
-> `grpc-plugin` is a package of its own rather than a target inside `grpc`, because
-> upstream's plugin links `grpc_plugin_support` + protobuf and nothing else — a code
-> generator needs a `.proto` parser and a C++ emitter, not TLS, DNS and a regex engine.
-> See `.agents/docs/2026-08-05-codegen-ecosystem-design.md` §2.
+Use `grpcgen::generate_all`, `plan_all` and `submit` for import paths, plugins and explicit build edges.
 
 ## Platform support
 
-**linux and macOS.** Not a gRPC limitation: `compat.openssl` has no windows entry yet
-("windows deferred — requires prebuilt MSVC libs"), so on windows dependency resolution
-fails with `E_NOT_FOUND: package 'compat:openssl@3.5.1' not found` before anything is
-compiled. gRPC's secure build cannot drop TLS, so this package's coverage is exactly
-that dependency's. The windows compile/link flags are already in `mcpp.toml`, ready for
-the day that entry lands.
+Runtime: Linux/macOS. Windows runtime is unavailable through the current OpenSSL provider; host tools are tested separately.
 
 ## Features
 
-| Feature | Default | Effect |
-|---|:---:|---|
-| `ares` | **on** | The c-ares asynchronous DNS resolver, matching upstream gRPC. Turn it off with `default-features = false`: 7 TUs and the `compat.c-ares` dependency drop out and `GRPC_ARES=0` is defined, so gRPC uses its native resolver — upstream's own `grpc_no_ares=true` configuration. |
-
-```toml
-[dependencies.grpc]
-grpc = { version = "1.83.0", default-features = false }   # no c-ares
-```
+| Feature | Purpose |
+|---|---|
+| `codegen` | protoc, C++ plugin and host rule |
+| `ares` | c-ares DNS resolver |
 
 ## How it is built
 
-```
-third_party/grpc-1.83.0/   pinned upstream source, zero patches
-src/grpc.cppm              the C++23 module interface (also the lib root)
-tools/gen_sources.py       regenerates the source list from upstream CMakeLists.txt
-build.mcpp                 private include dirs + the `ares` off-state
-rules/                     `grpcgen` — the codegen rule package (host module)
-plugin/                    `grpc_cpp_plugin` — the codegen tool, its own package
-examples/greeter/          the template instantiated: 3-line build.mcpp
-examples/helloworld/       the same program with the rule written out by hand
-```
-
-The 995-entry source list in `mcpp.toml` is **upstream's own** — the union of
-`add_library(gpr)`, `add_library(grpc)`, `add_library(grpc++)` and
-`add_library(address_sorting)` — and `tools/gen_sources.py --check` runs in CI to prove
-the manifest has not drifted from the vendored tree.
-
-One file from that union is deliberately excluded:
-`src/core/ext/upb-gen/google/protobuf/descriptor.upb_minitable.c`, which is byte-for-byte
-identical to the bootstrap copy `compat.protobuf`'s `upb` feature already compiles —
-building both is a duplicate-symbol failure.
-
-### Why a repository rather than an index descriptor
-
-gRPC publishes **no self-contained source artifact**. Its tag archive carries
-abseil, protobuf, re2, boringssl and zlib as *empty submodule placeholders*, so there is
-nothing an index descriptor could point a `url` + `sha256` at. This repository's release
-tarball is that artifact.
-
-### Dependencies
-
-| Package | Why |
-|---|---|
-| `compat.abseil` | gRPC's base library, and protobuf's |
-| `compat.protobuf` + `upb` | the C++ runtime, plus the C runtime gRPC's generated `upb-gen` code links against |
-| `compat.re2` | the xds route matchers |
-| `compat.c-ares` | asynchronous DNS (the `ares` feature) |
-| `compat.openssl` | TLS. gRPC supports OpenSSL as a first-class provider — only 9 files in `src/core` have a BoringSSL branch, and OpenSSL is the default side |
-| `compat.zlib` | gRPC's own message compression (`deflate`/`inflate`) |
+Pinned gRPC sources plus indexed dependencies; private configuration stays in `build.mcpp`. [Details](docs/usage.md)
 
 ## Build and test locally
 
-```bash
-mcpp test                      # builds the library, runs the module test
-cd examples/greeter && mcpp run      # 3-line build.mcpp (via grpcgen)
-cd examples/helloworld && mcpp run   # same program, rule written by hand
+```sh
+mcpp build
+mcpp test
 ```
 
 ## License
 
-The module layer and build glue are Apache-2.0, matching vendored gRPC
-([LICENSE](LICENSE)). Each dependency keeps its own license.
+[Apache-2.0](LICENSE); preserve third-party dependency notices.
+
+Wrapper: Apache-2.0, mcpp-community. [Original upstream README and licenses](upstream/grpc/). Upstream licenses remain unchanged.
diff --git a/README.zh.md b/README.zh.md
index f3836ed..ca57d46 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,237 +1,77 @@
 # grpc-m
 
-> 面向 mcpp 的 gRPC 1.83.0 —— 从上游源码构建、`import grpc;` 即用、一条命令跑通一次真实 RPC
+> 从源码构建 gRPC 1.83.0，保留 grpc::，共享索引依赖。
+
+[English](README.md) · **简体中文** · [Upstream](https://github.com/grpc/grpc) · [Releases](https://github.com/mcpplibs/grpc-m/releases) · [mcpp](https://github.com/mcpp-community/mcpp) · [Index](https://github.com/mcpplibs/mcpp-index)
 
-[![Release](https://img.shields.io/github/v/release/mcpplibs/grpc-m)](https://github.com/mcpplibs/grpc-m/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
-[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
-[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
-[![gRPC 1.83.0](https://img.shields.io/badge/gRPC-1.83.0-brightgreen.svg)](https://github.com/grpc/grpc/releases/tag/v1.83.0)
+[![License](https://img.shields.io/badge/license-Apache-2.0-blue.svg)](LICENSE)
+[![mcpp-community](https://img.shields.io/badge/mcpp--community-mwrap-blue)](https://github.com/mcpp-community)
+[![CI](https://github.com/mcpplibs/grpc-m/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mcpplibs/grpc-m/actions/workflows/ci.yml)
+
+## 模块
 
-| [English](README.md) - 简体中文 |
-|:---:|
-| [mcpp 构建工具](https://github.com/mcpp-community/mcpp) · [包索引](https://github.com/mcpplibs/mcpp-index) · [Issues](https://github.com/mcpplibs/grpc-m/issues) |
+- `import mcpplibs.mwrap.grpc;`: grpc:: 客户端、服务端与状态 API
+- `import mcpplibs.mwrap.grpc.macros;`: 版本宏映射
 
-`grpc-m` 从上游源码构建 gRPC 的 C++ 栈,**零补丁**;abseil、protobuf、re2、c-ares、OpenSSL、zlib
-全部取自 [mcpp-index](https://github.com/mcpplibs/mcpp-index),而不是各自再 vendor 一份。
-无 CMake、无 Bazel、无 configure —— `mcpp build` 就是全部。
+> More Modules API -> [模块与 API](docs/usage.zh.md)
 
 ## 快速开始
 
-```bash
-mcpp new mygreeter --template grpc && cd mygreeter
+```sh
+mcpp new greeter --template mcpplibs.mwrap.grpc@1.83.0
+cd greeter
 mcpp run
 ```
 
-```
-server listening on 127.0.0.1:34733
-Greeter replied: Hello mcpp
-```
-
-或加入已有工程:
-
-```bash
-mcpp add grpc.grpc
-```
-
 ```toml
-[dependencies.grpc]
-grpc = "1.83.0"
+[dependencies]
+mcpplibs.mwrap.grpc = { version = "1.83.0", features = ["codegen"] }
 ```
 
-## 两种用法
-
-gRPC 的代码生成器产出的是**头文件**,所以任何真实程序都会 include protoc 的产物。模块层是
-你手写的那部分(服务端、通道、凭据)的更好写法。
-
-```cpp
-#include <string>                     // 标准库头在前
-#include "helloworld.grpc.pb.h"       // 然后是 protoc 产物
-import grpc;                          // 模块放最后 —— 原因见下
-
-class Greeter final : public helloworld::Greeter::Service {
-    grpc::Status SayHello(grpc::ServerContext*, const helloworld::HelloRequest* req,
-                          helloworld::HelloReply* rep) override {
-        rep->set_message("Hello " + req->name());
-        return grpc::Status::OK;
-    }
-};
-```
-
-> **`import grpc;` 必须放最后。** 该模块的 BMI 里带着标准库(它包裹 `<grpcpp/grpcpp.h>`,
-> 而后者会拉进大半个标准库),所以在 import **之后**再 textual include 会让同一批声明到达两次,
-> 构建直接失败 —— 报 `redefinition of std::__is_constant_evaluated`,或 `std::string` 上的
-> `ambiguous overload for operator==`。把所有 `#include` 放在 import 之前就一切正常:
-> 导出的实体属于**全局模块**,textual 视图与 import 视图是同一批实体。两种顺序均已用
-> gcc 16.1.0 实测验证。
-
-也可以完全不用模块,直接走头文件:
+## 两种使用方式
 
 ```cpp
-#include <grpcpp/grpcpp.h>
 #include "helloworld.grpc.pb.h"
+import mcpplibs.mwrap.grpc;
 ```
 
-## 代码生成
-
-gRPC 需要两个宿主工具 —— `protoc` 与 `grpc_cpp_plugin` —— 自 **mcpp 2026.8.5.1** 起
-你不再需要自己准备它们,也不需要知道它们是谁:
+标准库与生成头放在 import 前；也可直接使用 `<grpcpp/grpcpp.h>`。
+`.macros` 映射版本常量；预处理宏仍通过文本头使用。
 
-```toml
-[dependencies.grpc]
-grpc = { version = "1.83.0", features = ["codegen"] }
-```
-
-```cpp
-// build.mcpp —— 全文如此
-import mcpp;
-import grpcgen;
-int main() { return grpcgen::generate_all() ? 0 : 1; }
-```
-
-一条依赖,一行代码。gRPC 的代码生成需要哪些工具 —— protoc、C++ 插件、驱动它们
-的那条规则 —— 是**这个包**的知识,`features = ["codegen"]` 就是它说出这件事的
-地方。新增一个 `.proto` 只是往 `proto/` 里放一个文件,没有需要同步维护的清单。
-
-这就是 `templates/greeter`,`mcpp new --template grpc` 直接给你一份能建的
-(`--template` 接的是**包名**;一个包带多个模板时写成 `grpc:greeter`)。
-**仓库里不再签入任何生成产物** —— 改 `.proto` 然后重新构建,就这样。
+## 代码生成
 
-`grpcgen` 是一个普通的 mcpp 包,里面装着那条规则,用 C++ 写、与 gRPC 同版本发布。
-规则走你已经在用的包管理器分发,所以这里**没有第二门语言** —— 不像 xmake 用 Lua rule、
-Bazel 用 Starlark。它需要 **mcpp 2026.8.6.2**;2026.8.5.2 是规则包从那一版起才真正能用
-`import std;` 与 `import mcpp;` 的。
+`codegen` 提供 protoc、grpc_cpp_plugin 与宿主规则；默认模板实际生成存根。
+[规则 API 与生成头顺序](docs/usage.zh.md)
 
 ## 需要更多控制时
 
-`generate_all()` 之外不是断崖 —— 每一层都是下一层的默认值,**不是另一条路**:
-`generate_all(opt)` 就是 `submit(plan_all(opt))`,`.grpc = true` 就是
-`.plugins = {cpp()}`。
-
-```cpp
-// L1 —— 声明式旋钮
-grpcgen::generate_all({
-    .extra_dirs  = {"../shared-proto"},   // 也要生成的共享 .proto 树
-    .imports     = {"/opt/googleapis"},   // 只搜索,不生成
-    .mock        = true,                  // gRPC 的 generate_mock_code=true
-    .protoc_args = {"--experimental_allow_proto3_optional"},
-});
-
-// L2 —— 插件列表;`.grpc = true` 是「列表里有 cpp()」的语法糖
-grpcgen::generate_all({ .plugins = { grpcgen::cpp(), my_plugin } });
-
-// L3 —— plan / submit 分离:再离谱的需求也不必绕开规则
-auto edges = grpcgen::plan_all();
-for (auto& e : edges) e.arg("--whatever");
-grpcgen::submit(edges);
-```
-
-`extra_dirs` 与 `imports` 的区别不是学究:protoc 会把
-`#include "common/types.pb.h"` 写进任何 import 了它的文件,所以只靠 `-I` 够到的
-共享树会产出一个**没人生成**的头,报错还离原因很远。代码归你构建就用
-`extra_dirs`,代码来自别处(你已经链接的包)才用 `imports`。
-
-**可观测性的分工**:每条边的完整命令行由 mcpp 写进 `build.ninja`,
-`ninja -t commands <output>` 就能取 —— 规则不重造。规则负责的是「**哪些旋钮**产生
-了它」,写在每次构建都会打印的 description 里:
-
-```
-GENERATE protoc:orders (+grpc +mock, -Iproto -I../shared-proto)
-```
-
-`examples/advanced` 覆盖 L1 + L3。
-
-三个示例,是刻意的:
-
-| | |
-|---|---|
-| `examples/greeter` | 模板的实例化 —— 经 `grpcgen`,`build.mcpp` 三行 |
-| `examples/helloworld` | 同一个程序,但把规则手工摊开写,让机制保持可读 |
-| `examples/advanced` | 分层旋钮:跨根生成的共享 .proto 树、gRPC mock、plan/submit 中间加断言 |
-
-由此得到三个手工管理 codegen 给不了的性质:
-
-- **版本错配不可表达。** 工具的版本**就是**那条依赖的版本,所以「protoc 与 protobuf
-  运行时对不上」——这是**运行期**才炸、也是 protobuf codegen 最难查的一类问题——
-  在语法上无法发生。(Conan 为了近似这一点专门引入了 `<host_version>` 占位符;
-  protobuf 自己的 CMake 至今有一个 open issue:CONFIG 模式下 `Protobuf_PROTOC_EXECUTABLE`
-  被忽略。)
-- **增量。** 生成是一条 ninja 边,`.proto` 变了才重跑,不变就不跑。
-- **交叉编译构造上就对。** `--target` 下工具依然为构建机器构建,你什么都不用做。
-
-> `grpc-plugin` 是独立的包而不是 `grpc` 里的一个 target,因为上游的插件只链
-> `grpc_plugin_support` + protobuf,别的都不链 —— 一个代码生成器需要的是 `.proto`
-> 解析器和 C++ 发射器,不是 TLS、DNS 和正则引擎。
-> 详见 `.agents/docs/2026-08-05-codegen-ecosystem-design.md` §2。
+使用 `grpcgen::generate_all`、`plan_all`、`submit` 配置导入目录、插件与显式构建边。
 
 ## 平台支持
 
-**linux 与 macOS。** 这不是 gRPC 的限制:`compat.openssl` 目前没有 windows 条目
-(其描述符写着 "windows deferred —— 需要预编译的 MSVC 库"),因此在 windows 上依赖解析
-会直接失败 —— `E_NOT_FOUND: package 'compat:openssl@3.5.1' not found`,还没开始编译。
-gRPC 的 secure 构建无法去掉 TLS,所以本包的平台覆盖面就等于该依赖的覆盖面。
-windows 所需的编译/链接选项已经写在 `mcpp.toml` 里,等那个条目落地即可启用。
-
-## Features
+运行时支持 Linux/macOS；当前 OpenSSL 供应者未支持 Windows 运行时，宿主工具单独测试。
 
-| Feature | 默认 | 作用 |
-|---|:---:|---|
-| `ares` | **开** | c-ares 异步 DNS 解析器,与上游 gRPC 一致。用 `default-features = false` 关闭:7 个 TU 与 `compat.c-ares` 依赖一并移除,并定义 `GRPC_ARES=0`,gRPC 改用原生解析器 —— 即上游自己的 `grpc_no_ares=true` 配置。 |
+## 特性
 
-```toml
-[dependencies.grpc]
-grpc = { version = "1.83.0", default-features = false }   # 不带 c-ares
-```
+| Feature | 用途 |
+|---|---|
+| `codegen` | protoc、C++ 插件与宿主规则 |
+| `ares` | c-ares DNS 解析器 |
 
 ## 构建方式
 
-```
-third_party/grpc-1.83.0/   钉住的上游源码,零补丁
-src/grpc.cppm              C++23 模块接口(同时也是 lib root)
-tools/gen_sources.py       从上游 CMakeLists.txt 重新生成源码清单
-build.mcpp                 私有 include 目录 + `ares` 的关闭态
-rules/                     `grpcgen` —— codegen 规则包(host module)
-plugin/                    `grpc_cpp_plugin` —— 独立的 codegen 工具包
-examples/greeter/          模板实例化:三行 build.mcpp
-examples/helloworld/       同一个程序,规则手工摊开写
-examples/advanced/         分层旋钮(extra_dirs / mock / plan-submit)
-examples/shared-proto/     被 advanced 跨根生成的共享 .proto 树
-```
-
-`mcpp.toml` 里那份 995 条的源码清单是**上游自己的** —— `add_library(gpr)`、
-`add_library(grpc)`、`add_library(grpc++)`、`add_library(address_sorting)` 四者之并 ——
-CI 会跑 `tools/gen_sources.py --check`,证明 manifest 与 vendored 源码树没有漂移。
-
-其中刻意排除了一个文件:`src/core/ext/upb-gen/google/protobuf/descriptor.upb_minitable.c`,
-它与 `compat.protobuf` 的 `upb` feature 已经编译的 bootstrap 版本**逐字节完全相同**,
-两份同时编入会重复符号。
-
-### 为什么是独立仓库而不是索引描述符
-
-gRPC **不发布任何自包含的源码产物**。它的 tag 归档里 abseil、protobuf、re2、boringssl、zlib
-全是*空的 submodule 占位*,索引描述符的 `url` + `sha256` 无处可指。本仓库的 release tarball
-就是那个产物。
-
-### 依赖
-
-| 包 | 原因 |
-|---|---|
-| `compat.abseil` | gRPC 的基础库,也是 protobuf 的 |
-| `compat.protobuf` + `upb` | C++ 运行时,外加 gRPC 生成的 `upb-gen` 代码所链接的 C 运行时 |
-| `compat.re2` | xds 路由匹配器 |
-| `compat.c-ares` | 异步 DNS(`ares` feature) |
-| `compat.openssl` | TLS。gRPC 官方支持 OpenSSL —— `src/core` 里只有 9 个文件带 BoringSSL 分支,且 OpenSSL 是默认那一侧 |
-| `compat.zlib` | gRPC 自己的消息压缩(`deflate`/`inflate`) |
+固定 gRPC 源码配合索引依赖，私有配置位于 `build.mcpp`；见[详情](docs/usage.zh.md)。
 
 ## 本地构建与测试
 
-```bash
-mcpp test                      # 构建库并运行模块测试
-cd examples/greeter && mcpp run      # 三行 build.mcpp(经 grpcgen)
-cd examples/helloworld && mcpp run   # 同一个程序,规则手写
+```sh
+mcpp build
+mcpp test
 ```
 
-## License
+## 许可证
+
+[Apache-2.0](LICENSE)；保留第三方依赖通知。
 
-模块层与构建胶水为 Apache-2.0,与 vendored 的 gRPC 一致([LICENSE](LICENSE))。
-各依赖保留其自身许可证。
+封装：Apache-2.0，mcpp-community。[上游原始 README 与许可证](upstream/grpc/)，上游许可保持原样。
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..9b57217
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,271 @@
+Detailed usage and background. See the [README](../README.md) for the current candidate quickstart and support boundary.
+
+# grpc-m
+
+> gRPC 1.83.0 for mcpp — built from upstream source, `import mcpplibs.mwrap.grpc;` ready, one command to a working RPC
+
+[![Release](https://img.shields.io/github/v/release/mcpplibs/grpc-m)](https://github.com/mcpplibs/grpc-m/releases)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
+[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
+[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](../LICENSE)
+[![gRPC 1.83.0](https://img.shields.io/badge/gRPC-1.83.0-brightgreen.svg)](https://github.com/grpc/grpc/releases/tag/v1.83.0)
+
+| English - [简体中文](../README.zh.md) |
+|:---:|
+| [mcpp build tool](https://github.com/mcpp-community/mcpp) · [package index](https://github.com/mcpplibs/mcpp-index) · [Issues](https://github.com/mcpplibs/grpc-m/issues) |
+
+`grpc-m` builds gRPC's C++ stack from upstream source with **zero patches**, and takes
+abseil, protobuf, re2, c-ares, OpenSSL and zlib from
+[mcpp-index](https://github.com/mcpplibs/mcpp-index) rather than vendoring a second copy
+of each. No CMake, no Bazel, no configure step — `mcpp build` is the whole story.
+
+## Quick Start
+
+```bash
+mcpp new mygreeter --template grpc && cd mygreeter
+mcpp run
+```
+
+```
+server listening on 127.0.0.1:34733
+Greeter replied: Hello mcpp
+```
+
+Or add it to an existing project:
+
+```bash
+mcpp add mcpplibs.mwrap.grpc
+```
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = "1.83.0"
+```
+
+## Two ways to use it
+
+gRPC's code generator emits **headers**, so any real program includes protoc output. The
+module is the ergonomic surface for everything you write by hand around it.
+
+```cpp
+#include <string>                     // std headers first
+#include "helloworld.grpc.pb.h"       // then protoc output
+import mcpplibs.mwrap.grpc;                          // the module LAST — see below
+
+class Greeter final : public helloworld::Greeter::Service {
+    grpc::Status SayHello(grpc::ServerContext*, const helloworld::HelloRequest* req,
+                          helloworld::HelloReply* rep) override {
+        rep->set_message("Hello " + req->name());
+        return grpc::Status::OK;
+    }
+};
+```
+
+> **`import mcpplibs.mwrap.grpc;` goes last.** The module carries the standard library in its BMI (it
+> wraps `<grpcpp/grpcpp.h>`, which pulls in most of it), so a textual `#include` *after*
+> the import delivers a second copy and the build fails — `redefinition of
+> std::__is_constant_evaluated`, or `ambiguous overload for operator==` on `std::string`.
+> Put every `#include` above the import and everything resolves: the exported entities
+> belong to the **global module**, so the textual and imported views are the same
+> entities. Verified both ways round with gcc 16.1.0.
+
+Prefer plain headers instead? That works too and needs no import at all:
+
+```cpp
+#include <grpcpp/grpcpp.h>
+#include "helloworld.grpc.pb.h"
+```
+
+## Code generation
+
+gRPC needs two host tools — `protoc` and `grpc_cpp_plugin` — and since **mcpp 2026.8.5.1**
+you no longer supply them yourself. Declare them on the dependencies they belong to, add
+the codegen rule, and that is the entire setup:
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = { version = "1.83.0", features = ["codegen"] }
+```
+
+```cpp
+// build.mcpp — in full
+import mcpp;
+import grpcgen;
+int main() { return grpcgen::generate_all() ? 0 : 1; }
+```
+
+One dependency and one line. Which tools gRPC codegen needs — protoc, the C++
+plugin, the rule that drives them — is this package's knowledge, and
+`features = ["codegen"]` is where it says so. Adding a `.proto` means dropping
+a file in `proto/`; there is no list to keep in sync.
+
+That is `templates/greeter`, and `mcpp new --template grpc` gives it to you ready to
+build (`--template` takes the PACKAGE; spell the template out as `grpc:greeter` when a
+package ships more than one). **No generated file is checked in any more** — edit the `.proto` and rebuild.
+
+`grpcgen` is an ordinary mcpp package holding the rule, written in C++ and versioned
+alongside gRPC. Rules ship through the package manager you already have, so there is no
+second language here the way xmake has Lua rules and Bazel has Starlark. It needs
+**mcpp 2026.8.6.2** — 2026.8.5.2 is where a rule package first became able to use `import std;`
+and `import mcpp;`.
+
+## When you need more control
+
+Past `generate_all()` there is no cliff — each layer is the next one's
+**defaults, not another road**: `generate_all(opt)` *is* `submit(plan_all(opt))`,
+and `.grpc = true` *is* `.plugins = {cpp()}`.
+
+```cpp
+// L1 — declarative knobs
+grpcgen::generate_all({
+    .extra_dirs  = {"../shared-proto"},   // shared .proto tree, generated too
+    .imports     = {"/opt/googleapis"},   // search only, not generated
+    .mock        = true,                  // gRPC's generate_mock_code=true
+    .protoc_args = {"--experimental_allow_proto3_optional"},
+});
+
+// L2 — the plugin list; `.grpc = true` is sugar for "cpp() is in it"
+grpcgen::generate_all({ .plugins = { grpcgen::cpp(), my_plugin } });
+
+// L3 — plan / submit: no requirement is exotic enough to need bypassing the rule
+auto edges = grpcgen::plan_all();
+for (auto& e : edges) e.arg("--whatever");
+grpcgen::submit(edges);
+```
+
+`extra_dirs` vs `imports` is not a pedantic distinction: protoc writes
+`#include "common/types.pb.h"` into every file that imports that .proto, so a
+shared tree reached only through `-I` yields a header **nobody produced**, and
+the failure surfaces far from its cause. Use `extra_dirs` when that code is
+yours to build; `imports` when it comes from somewhere you already link.
+
+**Observability, and whose job it is**: mcpp writes each edge's full argv into
+`build.ninja` — `ninja -t commands <output>` recovers it, and the rule does not
+duplicate that. What the rule owns is *which knobs* produced the command, and it
+puts that in the description every build prints:
+
+```
+GENERATE protoc:orders (+grpc +mock, -Iproto -I../shared-proto)
+```
+
+`examples/advanced` covers L1 + L3.
+
+Three examples, on purpose:
+
+| | |
+|---|---|
+| `examples/greeter` | the template instantiated — 3-line `build.mcpp` via `grpcgen` |
+| `examples/helloworld` | the same program with the rule written out by hand, so the mechanism stays legible |
+| `examples/advanced` | the layered knobs: a shared .proto tree generated across roots, gRPC mocks, and plan/submit with an assertion in between |
+
+Three properties this buys, none of which hand-managed codegen can offer:
+
+- **A version mismatch is not expressible.** A tool's version *is* its dependency's
+  version, so a `protoc` that disagrees with the protobuf runtime — a **runtime** failure,
+  and the nastiest thing about protobuf codegen — cannot happen. (Conan needed a
+  `<host_version>` placeholder to approximate this; protobuf's own CMake still has an open
+  issue where `Protobuf_PROTOC_EXECUTABLE` is ignored in CONFIG mode.)
+- **Incremental.** Generation is a ninja edge, so it re-runs when its `.proto` changes and
+  not otherwise.
+- **Cross-compilation is correct by construction.** Under `--target` the tools are still
+  built for the build machine, with no action from you.
+
+> `grpc-plugin` is a package of its own rather than a target inside `mcpplibs.mwrap.grpc`, because
+> upstream's plugin links `grpc_plugin_support` + protobuf and nothing else — a code
+> generator needs a `.proto` parser and a C++ emitter, not TLS, DNS and a regex engine.
+> See `.agents/docs/2026-08-05-codegen-ecosystem-design.md` §2.
+
+## Platform support
+
+**linux and macOS.** Not a gRPC limitation: `compat.openssl` has no windows entry yet
+("windows deferred — requires prebuilt MSVC libs"), so on windows dependency resolution
+fails with `E_NOT_FOUND: package 'compat:openssl@3.5.1' not found` before anything is
+compiled. gRPC's secure build cannot drop TLS, so this package's coverage is exactly
+that dependency's. The windows compile/link flags are already in `mcpp.toml`, ready for
+the day that entry lands.
+
+## Features
+
+| Feature | Default | Effect |
+|---|:---:|---|
+| `ares` | **on** | The c-ares asynchronous DNS resolver, matching upstream gRPC. Turn it off with `default-features = false`: 7 TUs and the `compat.c-ares` dependency drop out and `GRPC_ARES=0` is defined, so gRPC uses its native resolver — upstream's own `grpc_no_ares=true` configuration. |
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = { version = "1.83.0", default-features = false }   # no c-ares
+```
+
+## How it is built
+
+```
+third_party/grpc-1.83.0/   pinned upstream source, zero patches
+src/grpc.cppm              the C++23 module interface (also the lib root)
+tools/gen_sources.py       regenerates the source list from upstream CMakeLists.txt
+build.mcpp                 private include dirs + the `ares` off-state
+rules/                     `grpcgen` — the codegen rule package (host module)
+plugin/                    `grpc_cpp_plugin` — the codegen tool, its own package
+examples/greeter/          the template instantiated: 3-line build.mcpp
+examples/helloworld/       the same program with the rule written out by hand
+```
+
+The 995-entry source list in `mcpp.toml` is **upstream's own** — the union of
+`add_library(gpr)`, `add_library(grpc)`, `add_library(grpc++)` and
+`add_library(address_sorting)` — and `tools/gen_sources.py --check` runs in CI to prove
+the manifest has not drifted from the vendored tree.
+
+One file from that union is deliberately excluded:
+`src/core/ext/upb-gen/google/protobuf/descriptor.upb_minitable.c`, which is byte-for-byte
+identical to the bootstrap copy `compat.protobuf`'s `upb` feature already compiles —
+building both is a duplicate-symbol failure.
+
+### Why a repository rather than an index descriptor
+
+gRPC publishes **no self-contained source artifact**. Its tag archive carries
+abseil, protobuf, re2, boringssl and zlib as *empty submodule placeholders*, so there is
+nothing an index descriptor could point a `url` + `sha256` at. This repository's release
+tarball is that artifact.
+
+### Dependencies
+
+| Package | Why |
+|---|---|
+| `compat.abseil` | gRPC's base library, and protobuf's |
+| `compat.protobuf` + `upb` | the C++ runtime, plus the C runtime gRPC's generated `upb-gen` code links against |
+| `compat.re2` | the xds route matchers |
+| `compat.c-ares` | asynchronous DNS (the `ares` feature) |
+| `compat.openssl` | TLS. gRPC supports OpenSSL as a first-class provider — only 9 files in `src/core` have a BoringSSL branch, and OpenSSL is the default side |
+| `compat.zlib` | gRPC's own message compression (`deflate`/`inflate`) |
+
+## Build and test locally
+
+```bash
+mcpp test                      # builds the library, runs the module test
+cd examples/greeter && mcpp run      # 3-line build.mcpp (via grpcgen)
+cd examples/helloworld && mcpp run   # same program, rule written by hand
+```
+
+## License
+
+The module layer and build glue are Apache-2.0, matching vendored gRPC
+([LICENSE](../LICENSE)). Each dependency keeps its own license.
+
+
+## Current-client quickstart candidate
+
+The wrapper revision is `1.83.0.1`; the upstream C/C++ API and published module
+identity stay unchanged. Development tooling uses mcpp `2026.10.24.1`. Templates
+now write one qualified dependency from `self.name`, without repeating a namespace.
+
+```sh
+mcpp new quickstart --template mcpplibs.mwrap.grpc@1.83.0.1:greeter
+cd quickstart
+mcpp run
+```
+
+This revision is a PR candidate until its source archive and index entry are
+validated. `tools/test_template.py` exercises actual `mcpp new`, checks the
+rendered dependency, strictly builds the candidate and runs it.
+
+The `codegen` feature takes its plugin and rule from this same source artifact.
+Host rule libraries use `[build-dependencies]`; protoc/plugin compilation remains
+conditional on `codegen`. The runtime, plugin and rule share the wrapper revision.
diff --git a/docs/usage.zh.md b/docs/usage.zh.md
new file mode 100644
index 0000000..1ef2bdf
--- /dev/null
+++ b/docs/usage.zh.md
@@ -0,0 +1,239 @@
+详细使用与背景说明；当前候选版本的快捷入口与支持边界见 [README](../README.zh.md)。
+
+# grpc-m
+
+> 面向 mcpp 的 gRPC 1.83.0 —— 从上游源码构建、`import mcpplibs.mwrap.grpc;` 即用、一条命令跑通一次真实 RPC
+
+[![Release](https://img.shields.io/github/v/release/mcpplibs/grpc-m)](https://github.com/mcpplibs/grpc-m/releases)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
+[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
+[![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](../LICENSE)
+[![gRPC 1.83.0](https://img.shields.io/badge/gRPC-1.83.0-brightgreen.svg)](https://github.com/grpc/grpc/releases/tag/v1.83.0)
+
+| [English](../README.md) - 简体中文 |
+|:---:|
+| [mcpp 构建工具](https://github.com/mcpp-community/mcpp) · [包索引](https://github.com/mcpplibs/mcpp-index) · [Issues](https://github.com/mcpplibs/grpc-m/issues) |
+
+`grpc-m` 从上游源码构建 gRPC 的 C++ 栈,**零补丁**;abseil、protobuf、re2、c-ares、OpenSSL、zlib
+全部取自 [mcpp-index](https://github.com/mcpplibs/mcpp-index),而不是各自再 vendor 一份。
+无 CMake、无 Bazel、无 configure —— `mcpp build` 就是全部。
+
+## 快速开始
+
+```bash
+mcpp new mygreeter --template grpc && cd mygreeter
+mcpp run
+```
+
+```
+server listening on 127.0.0.1:34733
+Greeter replied: Hello mcpp
+```
+
+或加入已有工程:
+
+```bash
+mcpp add mcpplibs.mwrap.grpc
+```
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = "1.83.0"
+```
+
+## 两种用法
+
+gRPC 的代码生成器产出的是**头文件**,所以任何真实程序都会 include protoc 的产物。模块层是
+你手写的那部分(服务端、通道、凭据)的更好写法。
+
+```cpp
+#include <string>                     // 标准库头在前
+#include "helloworld.grpc.pb.h"       // 然后是 protoc 产物
+import mcpplibs.mwrap.grpc;                          // 模块放最后 —— 原因见下
+
+class Greeter final : public helloworld::Greeter::Service {
+    grpc::Status SayHello(grpc::ServerContext*, const helloworld::HelloRequest* req,
+                          helloworld::HelloReply* rep) override {
+        rep->set_message("Hello " + req->name());
+        return grpc::Status::OK;
+    }
+};
+```
+
+> **`import mcpplibs.mwrap.grpc;` 必须放最后。** 该模块的 BMI 里带着标准库(它包裹 `<grpcpp/grpcpp.h>`,
+> 而后者会拉进大半个标准库),所以在 import **之后**再 textual include 会让同一批声明到达两次,
+> 构建直接失败 —— 报 `redefinition of std::__is_constant_evaluated`,或 `std::string` 上的
+> `ambiguous overload for operator==`。把所有 `#include` 放在 import 之前就一切正常:
+> 导出的实体属于**全局模块**,textual 视图与 import 视图是同一批实体。两种顺序均已用
+> gcc 16.1.0 实测验证。
+
+也可以完全不用模块,直接走头文件:
+
+```cpp
+#include <grpcpp/grpcpp.h>
+#include "helloworld.grpc.pb.h"
+```
+
+## 代码生成
+
+gRPC 需要两个宿主工具 —— `protoc` 与 `grpc_cpp_plugin` —— 自 **mcpp 2026.8.5.1** 起
+你不再需要自己准备它们,也不需要知道它们是谁:
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = { version = "1.83.0", features = ["codegen"] }
+```
+
+```cpp
+// build.mcpp —— 全文如此
+import mcpp;
+import grpcgen;
+int main() { return grpcgen::generate_all() ? 0 : 1; }
+```
+
+一条依赖,一行代码。gRPC 的代码生成需要哪些工具 —— protoc、C++ 插件、驱动它们
+的那条规则 —— 是**这个包**的知识,`features = ["codegen"]` 就是它说出这件事的
+地方。新增一个 `.proto` 只是往 `proto/` 里放一个文件,没有需要同步维护的清单。
+
+这就是 `templates/greeter`,`mcpp new --template grpc` 直接给你一份能建的
+(`--template` 接的是**包名**;一个包带多个模板时写成 `grpc:greeter`)。
+**仓库里不再签入任何生成产物** —— 改 `.proto` 然后重新构建,就这样。
+
+`grpcgen` 是一个普通的 mcpp 包,里面装着那条规则,用 C++ 写、与 gRPC 同版本发布。
+规则走你已经在用的包管理器分发,所以这里**没有第二门语言** —— 不像 xmake 用 Lua rule、
+Bazel 用 Starlark。它需要 **mcpp 2026.8.6.2**;2026.8.5.2 是规则包从那一版起才真正能用
+`import std;` 与 `import mcpp;` 的。
+
+## 需要更多控制时
+
+`generate_all()` 之外不是断崖 —— 每一层都是下一层的默认值,**不是另一条路**:
+`generate_all(opt)` 就是 `submit(plan_all(opt))`,`.grpc = true` 就是
+`.plugins = {cpp()}`。
+
+```cpp
+// L1 —— 声明式旋钮
+grpcgen::generate_all({
+    .extra_dirs  = {"../shared-proto"},   // 也要生成的共享 .proto 树
+    .imports     = {"/opt/googleapis"},   // 只搜索,不生成
+    .mock        = true,                  // gRPC 的 generate_mock_code=true
+    .protoc_args = {"--experimental_allow_proto3_optional"},
+});
+
+// L2 —— 插件列表;`.grpc = true` 是「列表里有 cpp()」的语法糖
+grpcgen::generate_all({ .plugins = { grpcgen::cpp(), my_plugin } });
+
+// L3 —— plan / submit 分离:再离谱的需求也不必绕开规则
+auto edges = grpcgen::plan_all();
+for (auto& e : edges) e.arg("--whatever");
+grpcgen::submit(edges);
+```
+
+`extra_dirs` 与 `imports` 的区别不是学究:protoc 会把
+`#include "common/types.pb.h"` 写进任何 import 了它的文件,所以只靠 `-I` 够到的
+共享树会产出一个**没人生成**的头,报错还离原因很远。代码归你构建就用
+`extra_dirs`,代码来自别处(你已经链接的包)才用 `imports`。
+
+**可观测性的分工**:每条边的完整命令行由 mcpp 写进 `build.ninja`,
+`ninja -t commands <output>` 就能取 —— 规则不重造。规则负责的是「**哪些旋钮**产生
+了它」,写在每次构建都会打印的 description 里:
+
+```
+GENERATE protoc:orders (+grpc +mock, -Iproto -I../shared-proto)
+```
+
+`examples/advanced` 覆盖 L1 + L3。
+
+三个示例,是刻意的:
+
+| | |
+|---|---|
+| `examples/greeter` | 模板的实例化 —— 经 `grpcgen`,`build.mcpp` 三行 |
+| `examples/helloworld` | 同一个程序,但把规则手工摊开写,让机制保持可读 |
+| `examples/advanced` | 分层旋钮:跨根生成的共享 .proto 树、gRPC mock、plan/submit 中间加断言 |
+
+由此得到三个手工管理 codegen 给不了的性质:
+
+- **版本错配不可表达。** 工具的版本**就是**那条依赖的版本,所以「protoc 与 protobuf
+  运行时对不上」——这是**运行期**才炸、也是 protobuf codegen 最难查的一类问题——
+  在语法上无法发生。(Conan 为了近似这一点专门引入了 `<host_version>` 占位符;
+  protobuf 自己的 CMake 至今有一个 open issue:CONFIG 模式下 `Protobuf_PROTOC_EXECUTABLE`
+  被忽略。)
+- **增量。** 生成是一条 ninja 边,`.proto` 变了才重跑,不变就不跑。
+- **交叉编译构造上就对。** `--target` 下工具依然为构建机器构建,你什么都不用做。
+
+> `grpc-plugin` 是独立的包而不是 `mcpplibs.mwrap.grpc` 里的一个 target,因为上游的插件只链
+> `grpc_plugin_support` + protobuf,别的都不链 —— 一个代码生成器需要的是 `.proto`
+> 解析器和 C++ 发射器,不是 TLS、DNS 和正则引擎。
+> 详见 `.agents/docs/2026-08-05-codegen-ecosystem-design.md` §2。
+
+## 平台支持
+
+**linux 与 macOS。** 这不是 gRPC 的限制:`compat.openssl` 目前没有 windows 条目
+(其描述符写着 "windows deferred —— 需要预编译的 MSVC 库"),因此在 windows 上依赖解析
+会直接失败 —— `E_NOT_FOUND: package 'compat:openssl@3.5.1' not found`,还没开始编译。
+gRPC 的 secure 构建无法去掉 TLS,所以本包的平台覆盖面就等于该依赖的覆盖面。
+windows 所需的编译/链接选项已经写在 `mcpp.toml` 里,等那个条目落地即可启用。
+
+## Features
+
+| Feature | 默认 | 作用 |
+|---|:---:|---|
+| `ares` | **开** | c-ares 异步 DNS 解析器,与上游 gRPC 一致。用 `default-features = false` 关闭:7 个 TU 与 `compat.c-ares` 依赖一并移除,并定义 `GRPC_ARES=0`,gRPC 改用原生解析器 —— 即上游自己的 `grpc_no_ares=true` 配置。 |
+
+```toml
+[dependencies.mcpplibs.mwrap]
+grpc = { version = "1.83.0", default-features = false }   # 不带 c-ares
+```
+
+## 构建方式
+
+```
+third_party/grpc-1.83.0/   钉住的上游源码,零补丁
+src/grpc.cppm              C++23 模块接口(同时也是 lib root)
+tools/gen_sources.py       从上游 CMakeLists.txt 重新生成源码清单
+build.mcpp                 私有 include 目录 + `ares` 的关闭态
+rules/                     `grpcgen` —— codegen 规则包(host module)
+plugin/                    `grpc_cpp_plugin` —— 独立的 codegen 工具包
+examples/greeter/          模板实例化:三行 build.mcpp
+examples/helloworld/       同一个程序,规则手工摊开写
+examples/advanced/         分层旋钮(extra_dirs / mock / plan-submit)
+examples/shared-proto/     被 advanced 跨根生成的共享 .proto 树
+```
+
+`mcpp.toml` 里那份 995 条的源码清单是**上游自己的** —— `add_library(gpr)`、
+`add_library(grpc)`、`add_library(grpc++)`、`add_library(address_sorting)` 四者之并 ——
+CI 会跑 `tools/gen_sources.py --check`,证明 manifest 与 vendored 源码树没有漂移。
+
+其中刻意排除了一个文件:`src/core/ext/upb-gen/google/protobuf/descriptor.upb_minitable.c`,
+它与 `compat.protobuf` 的 `upb` feature 已经编译的 bootstrap 版本**逐字节完全相同**,
+两份同时编入会重复符号。
+
+### 为什么是独立仓库而不是索引描述符
+
+gRPC **不发布任何自包含的源码产物**。它的 tag 归档里 abseil、protobuf、re2、boringssl、zlib
+全是*空的 submodule 占位*,索引描述符的 `url` + `sha256` 无处可指。本仓库的 release tarball
+就是那个产物。
+
+### 依赖
+
+| 包 | 原因 |
+|---|---|
+| `compat.abseil` | gRPC 的基础库,也是 protobuf 的 |
+| `compat.protobuf` + `upb` | C++ 运行时,外加 gRPC 生成的 `upb-gen` 代码所链接的 C 运行时 |
+| `compat.re2` | xds 路由匹配器 |
+| `compat.c-ares` | 异步 DNS(`ares` feature) |
+| `compat.openssl` | TLS。gRPC 官方支持 OpenSSL —— `src/core` 里只有 9 个文件带 BoringSSL 分支,且 OpenSSL 是默认那一侧 |
+| `compat.zlib` | gRPC 自己的消息压缩(`deflate`/`inflate`) |
+
+## 本地构建与测试
+
+```bash
+mcpp test                      # 构建库并运行模块测试
+cd examples/greeter && mcpp run      # 三行 build.mcpp(经 grpcgen)
+cd examples/helloworld && mcpp run   # 同一个程序,规则手写
+```
+
+## License
+
+模块层与构建胶水为 Apache-2.0,与 vendored 的 gRPC 一致([LICENSE](../LICENSE))。
+各依赖保留其自身许可证。
diff --git a/examples/advanced/mcpp.toml b/examples/advanced/mcpp.toml
index 432aa9d..ed2dc0b 100644
--- a/examples/advanced/mcpp.toml
+++ b/examples/advanced/mcpp.toml
@@ -27,11 +27,13 @@ kind = "bin"
 main = "src/main.cpp"
 
 [dependencies]
-grpc        = { path = "../.." }
+"mcpplibs.mwrap.grpc"        = { path = "../.." }
 grpc-plugin = { path = "../../plugin", tools = ["grpc_cpp_plugin"] }
 
 [dependencies.mcpplibs]
-grpcgen = { path = "../../rules", host-module = true }
 
 [dependencies.compat]
 protobuf = { version = "35.1", tools = ["protoc"] }
+
+[build-dependencies]
+grpcgen = { path = "../../rules", host-module = true }
diff --git a/examples/greeter/mcpp.toml b/examples/greeter/mcpp.toml
index d4e717e..090aeec 100644
--- a/examples/greeter/mcpp.toml
+++ b/examples/greeter/mcpp.toml
@@ -41,7 +41,7 @@ kind = "bin"
 main = "src/main.cpp"
 
 [dependencies]
-grpc = { path = "../.." }
+"mcpplibs.mwrap.grpc" = { path = "../.." }
 # The gRPC C++ codegen plugin — a package of its own rather than a target
 # inside gRPC, because a code generator needs a .proto parser and a C++
 # emitter, not TLS, DNS and a regex engine.
@@ -49,6 +49,8 @@ grpc-plugin = { path = "../../plugin", tools = ["grpc_cpp_plugin"] }
 # The codegen RULE. `host-module = true` makes its module importable from
 # build.mcpp, which is why build.mcpp is three lines instead of sixty. It is
 # build-time only — not compiled into or linked with this project.
-grpcgen = { path = "../../rules", host-module = true }
 # protoc, pinned to the same protobuf this project links.
 compat.protobuf = { version = "35.1", tools = ["protoc"] }
+
+[build-dependencies]
+grpcgen = { path = "../../rules", host-module = true }
diff --git a/examples/greeter/src/main.cpp b/examples/greeter/src/main.cpp
index ceadccf..9145de8 100644
--- a/examples/greeter/src/main.cpp
+++ b/examples/greeter/src/main.cpp
@@ -24,6 +24,9 @@
 
 #include "helloworld.grpc.pb.h"
 
+// Generated protobuf headers stay textual; import the public module last.
+import mcpplibs.mwrap.grpc;
+
 namespace {
 
 class GreeterService final : public helloworld::Greeter::Service {
diff --git a/examples/helloworld/mcpp.toml b/examples/helloworld/mcpp.toml
index aa115d4..43fc839 100644
--- a/examples/helloworld/mcpp.toml
+++ b/examples/helloworld/mcpp.toml
@@ -36,7 +36,7 @@ kind = "bin"
 main = "src/main.cpp"
 
 [dependencies]
-grpc = { path = "../.." }
+"mcpplibs.mwrap.grpc" = { path = "../.." }
 # The two host tools. `grpc-plugin` is a package separate from `grpc` on
 # purpose: a code generator needs a .proto parser and a C++ emitter, not TLS,
 # DNS and a regex engine — see the design doc §2.
diff --git a/mcpp.toml b/mcpp.toml
index 9844dd2..951f21b 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -1,9 +1,12 @@
+# Module wrapper; upstream API preserved. Policy: mcpp-index/docs/mwrap.md.
 [package]
-name        = "grpc"
-version     = "1.83.0"
+namespace = "mcpplibs.mwrap"
+name = "grpc"
+version = "1.83.0"
 standard    = "c++23"
 description = "gRPC 1.83.0 for mcpp — upstream C++ source vendored and built by this manifest, with abseil / protobuf / re2 / c-ares / OpenSSL taken from mcpp-index instead of re-vendored."
-license     = "Apache-2.0"
+license = "Apache-2.0"
+authors = ["mcpp-community"]
 repo        = "https://github.com/mcpplibs/grpc-m"
 
 # linux + macOS only, and the reason is a dependency rather than gRPC itself:
@@ -61,6 +64,7 @@ sources = [
     # of a `kind = "lib"` package as src/<package tail>.cppm, so this file
     # is both the module and what satisfies that convention.
     "src/grpc.cppm",
+    "src/macros.cppm",
     "third_party/grpc-1.83.0/src/core/config/config_vars.cc",
     "third_party/grpc-1.83.0/src/core/config/config_vars_non_generated.cc",
     "third_party/grpc-1.83.0/src/core/config/load_config.cc",
@@ -1162,10 +1166,14 @@ compat.protobuf   = { version = "35.1", tools = ["protoc"], reexport = true }
 # The gRPC C++ codegen plugin — a package of its own rather than a target
 # inside gRPC, because a code generator needs a .proto parser and a C++
 # emitter, not TLS, DNS and a regex engine.
-grpc.grpc-plugin  = { version = "1.83.0", tools = ["grpc_cpp_plugin"], reexport = true }
+grpc.grpc-plugin  = { path = "plugin", tools = ["grpc_cpp_plugin"], reexport = true }
 # The rule itself, as an importable host module. Not upstream code, so it
 # lives in mcpplibs rather than in the grpc namespace.
-mcpplibs.grpcgen  = { version = "1.83.0", host-module = true, reexport = true }
+# Host libraries use the current build-dependency contract. Re-exporting the
+# small rule package makes it available to a consumer build.mcpp; the expensive
+# protoc/plugin tools above remain conditional on codegen.
+[build-dependencies]
+"mcpplibs.grpcgen" = { path = "rules", host-module = true, reexport = true }
 
 [target.'cfg(windows)'.build]
 cxxflags = [
@@ -1189,3 +1197,22 @@ ldflags = ["-lpthread", "-ldl", "-lm"]
 [target.'cfg(macos)'.build]
 ldflags = ["-lresolv"]
 
+
+[package.metadata.mwrap]
+upstream-version = "1.83.0"
+
+[[runtime.deploy]]
+from = "LICENSE"
+to = "licenses/grpc"
+
+[[runtime.deploy]]
+from = "NOTICE"
+to = "licenses/grpc"
+
+[[runtime.deploy]]
+from = "upstream/grpc/README.md"
+to = "licenses/grpc/upstream/grpc"
+
+[[runtime.deploy]]
+from = "upstream/grpc/LICENSE"
+to = "licenses/grpc/upstream/grpc"
diff --git a/plugin/mcpp.toml b/plugin/mcpp.toml
index 6772320..ea5db35 100644
--- a/plugin/mcpp.toml
+++ b/plugin/mcpp.toml
@@ -23,7 +23,7 @@
 # See ../.agents/docs/2026-08-05-codegen-ecosystem-design.md §3.
 [package]
 name        = "grpc-plugin"
-version     = "1.83.0"
+version     = "1.83.0.1"
 standard    = "c++23"
 description = "grpc_cpp_plugin — the gRPC C++ code generator, buildable as an mcpp host tool"
 license     = "Apache-2.0"
diff --git a/rules/mcpp.toml b/rules/mcpp.toml
index 3df8f5a..8effbfb 100644
--- a/rules/mcpp.toml
+++ b/rules/mcpp.toml
@@ -5,8 +5,8 @@
 # as an ordinary library package that the consumer imports from its build
 # program:
 #
-#   [dependencies]
-#   grpcgen = { version = "1.83.0", host-module = true }
+#   [build-dependencies]
+#   grpcgen = { version = "1.83.0.1", host-module = true }
 #
 #   // build.mcpp
 #   import mcpp;
@@ -34,7 +34,7 @@
 # tag, and .github/workflows/ci.yml checks that they never drift apart.
 [package]
 name        = "grpcgen"
-version     = "1.83.0"
+version     = "1.83.0.1"
 standard    = "c++23"
 description = "protoc + grpc_cpp_plugin codegen as an importable mcpp build rule"
 license     = "Apache-2.0"
diff --git a/src/grpc.cppm b/src/grpc.cppm
index 46e75d9..378ef63 100644
--- a/src/grpc.cppm
+++ b/src/grpc.cppm
@@ -1,11 +1,11 @@
 // grpc — a C++23 module interface over gRPC's public C++ API.
 //
-// USAGE ORDER MATTERS. `import grpc;` goes LAST, after every textual #include
+// USAGE ORDER MATTERS. `import mcpplibs.mwrap.grpc;` goes LAST, after every textual #include
 // in the translation unit — the standard library ones included:
 //
 //     #include <string>                // std headers first
 //     #include "myservice.grpc.pb.h"   // protoc output too
-//     import grpc;                     // the module last
+//     import mcpplibs.mwrap.grpc;                     // the module last
 //
 // The reason is the global module fragment below. It pulls <grpcpp/grpcpp.h>,
 // which pulls most of the standard library, and all of it lands in this
@@ -46,7 +46,8 @@ module;
 #include <grpcpp/support/status.h>
 #include <grpcpp/support/sync_stream.h>
 
-export module grpc;
+export module mcpplibs.mwrap.grpc;
+export import mcpplibs.mwrap.grpc.macros;
 
 export namespace grpc {
 
@@ -135,3 +136,4 @@ export using ::GRPC_CHANNEL_CONNECTING;
 export using ::GRPC_CHANNEL_READY;
 export using ::GRPC_CHANNEL_TRANSIENT_FAILURE;
 export using ::GRPC_CHANNEL_SHUTDOWN;
+
diff --git a/src/macros.cppm b/src/macros.cppm
new file mode 100644
index 0000000..ded686e
--- /dev/null
+++ b/src/macros.cppm
@@ -0,0 +1,22 @@
+module;
+#include <grpcpp/version_info.h>
+namespace mwrap_grpc_capture {
+inline constexpr auto value_GRPC_CPP_VERSION_MAJOR = GRPC_CPP_VERSION_MAJOR;
+inline constexpr auto value_GRPC_CPP_VERSION_MINOR = GRPC_CPP_VERSION_MINOR;
+inline constexpr auto value_GRPC_CPP_VERSION_PATCH = GRPC_CPP_VERSION_PATCH;
+inline constexpr auto value_GRPC_CPP_VERSION_STRING = GRPC_CPP_VERSION_STRING;
+}
+#undef GRPC_CPP_VERSION_MAJOR
+#undef GRPC_CPP_VERSION_MINOR
+#undef GRPC_CPP_VERSION_PATCH
+#undef GRPC_CPP_VERSION_STRING
+
+export module mcpplibs.mwrap.grpc.macros;
+
+export namespace mcpplibs::mwrap::grpc::macros {
+inline constexpr auto GRPC_CPP_VERSION_MAJOR = mwrap_grpc_capture::value_GRPC_CPP_VERSION_MAJOR;
+inline constexpr auto GRPC_CPP_VERSION_MINOR = mwrap_grpc_capture::value_GRPC_CPP_VERSION_MINOR;
+inline constexpr auto GRPC_CPP_VERSION_PATCH = mwrap_grpc_capture::value_GRPC_CPP_VERSION_PATCH;
+inline constexpr auto GRPC_CPP_VERSION_STRING = mwrap_grpc_capture::value_GRPC_CPP_VERSION_STRING;
+
+}
diff --git a/templates/greeter/mcpp.toml.in b/templates/greeter/mcpp.toml.in
index 0af2a21..fb0b2cb 100644
--- a/templates/greeter/mcpp.toml.in
+++ b/templates/greeter/mcpp.toml.in
@@ -28,5 +28,5 @@ main = "src/main.cpp"
 # package's knowledge, not yours. The `grpc` namespace, because this is
 # UPSTREAM gRPC code: a namespace names whose library it is, not who packaged
 # it.
-[dependencies.grpc]
-{{self.name}} = { version = "{{self.version}}", features = ["codegen"] }
+[dependencies]
+"{{self.name}}" = { version = "{{self.version}}", features = ["codegen"] }
diff --git a/templates/greeter/src/main.cpp.in b/templates/greeter/src/main.cpp.in
index 1c4cb0e..a4ef8a2 100644
--- a/templates/greeter/src/main.cpp.in
+++ b/templates/greeter/src/main.cpp.in
@@ -24,6 +24,9 @@
 
 #include "helloworld.grpc.pb.h"
 
+// Generated protobuf headers stay textual; import the public module last.
+import mcpplibs.mwrap.grpc;
+
 namespace {
 
 class GreeterService final : public helloworld::Greeter::Service {
diff --git a/templates/greeter/template.toml b/templates/greeter/template.toml
index b0988e2..88ca45d 100644
--- a/templates/greeter/template.toml
+++ b/templates/greeter/template.toml
@@ -1,3 +1,4 @@
 [template]
+default = true
 description  = "Greeter service + client in one program — a real gRPC round trip over loopback"
 post_message = "cd into the project and `mcpp run`. The protobuf/gRPC stubs are NOT checked in: mcpp builds protoc and grpc_cpp_plugin from the same packages you link against, then generates the stubs during the build. Edit proto/helloworld.proto and rebuild — that is the whole workflow, and the generator can never be a different version from the runtime. To add a .proto, drop it in proto/ and build — build.mcpp picks up every .proto under that directory, so there is no list to maintain."
diff --git a/tests/macros.cpp b/tests/macros.cpp
new file mode 100644
index 0000000..c56b4b2
--- /dev/null
+++ b/tests/macros.cpp
@@ -0,0 +1,3 @@
+import mcpplibs.mwrap.grpc;
+namespace macros = mcpplibs::mwrap::grpc::macros;
+int main() { static_assert(macros::GRPC_CPP_VERSION_MAJOR == 1); static_assert(macros::GRPC_CPP_VERSION_MINOR == 83); return macros::GRPC_CPP_VERSION_STRING[0] != '1'; }
diff --git a/tests/module.cpp b/tests/module.cpp
index 837c3bd..7398430 100644
--- a/tests/module.cpp
+++ b/tests/module.cpp
@@ -1,6 +1,6 @@
 // Proves the `grpc` module is USABLE, not merely compilable.
 //
-// Everything here goes through `import grpc;` — there is no <grpcpp/...>
+// Everything here goes through `import mcpplibs.mwrap.grpc;` — there is no <grpcpp/...>
 // include anywhere in this file — and every call below reaches a real symbol
 // in libgrpc.a. A module that exported names but linked to nothing would fail.
 //
@@ -10,7 +10,7 @@
 // service needs protoc output, which belongs in the example rather than in a
 // test of the module surface. examples/helloworld covers that path end to end.
 //
-// Note the ORDER: every textual #include comes first, `import grpc;` last.
+// Note the ORDER: every textual #include comes first, `import mcpplibs.mwrap.grpc;` last.
 // That is not a style choice — this module carries the standard library in its
 // BMI, so a std header included AFTER the import arrives a second time and
 // GCC fails with "ambiguous overload for operator==" on std::string. See the
@@ -19,7 +19,7 @@
 #include <memory>
 #include <string>
 
-import grpc;
+import mcpplibs.mwrap.grpc;
 
 int main() {
     // 1. A version string read from the library, not a header constant.
diff --git a/tools/check_mwrap_release.py b/tools/check_mwrap_release.py
new file mode 100644
index 0000000..9bedddb
--- /dev/null
+++ b/tools/check_mwrap_release.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Check the immutable mwrap release coordinate and bilingual entry pages."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+import tomllib
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--tag', help='release tag; omitted during PR checks')
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parents[1]
+    package = tomllib.loads((root / 'mcpp.toml').read_text(encoding="utf-8"))['package']
+    assert package['namespace'] == 'mcpplibs.mwrap', package
+    assert re.fullmatch(r'[A-Za-z_][A-Za-z_0-9]*', package['name']), package['name']
+    upstream = package['metadata']['mwrap']['upstream-version']
+    version = package['version']
+    assert version == upstream or re.fullmatch(re.escape(upstream) + r'\.[1-9][0-9]*', version), (version, upstream)
+    if args.tag:
+        assert args.tag == 'mwrap-' + version, (args.tag, version)
+    assert package['license'] == 'Apache-2.0', package['license']
+    assert package['authors'] == ['mcpp-community'], package.get('authors')
+    license_text = (root / 'LICENSE').read_text(encoding='utf-8')
+    assert 'Apache License' in license_text and 'Version 2.0' in license_text
+    assert 'mcpp-community' in (root / 'NOTICE').read_text(encoding='utf-8')
+    documents = json.loads((root / 'upstream/documents.json').read_text(encoding='utf-8'))['documents']
+    assert any(Path(d['path']).name.startswith('README') for d in documents)
+    assert any(Path(d['path']).name.startswith(('LICENSE', 'COPYING')) for d in documents)
+    deployed = {entry['from'] for entry in tomllib.loads((root / 'mcpp.toml').read_text(encoding='utf-8')).get('runtime', {}).get('deploy', [])}
+    assert {'LICENSE', 'NOTICE'} <= deployed
+    for document in documents:
+        path = Path(document['path'])
+        assert not path.is_absolute() and '..' not in path.parts and path.parts[0] == 'upstream'
+        assert hashlib.sha256((root / path).read_bytes()).hexdigest() == document['sha256'], path
+        assert document['source'] and path.as_posix() in deployed, path
+    identity = package['namespace'] + '.' + package['name']
+    for name, other in [('README.md', 'README.zh.md'), ('README.zh.md', 'README.md')]:
+        text = (root / name).read_text(encoding="utf-8")
+        assert len(text.splitlines()) <= 150, name
+        assert '](' + other + ')' in '\n'.join(text.splitlines()[:12]), name
+        assert identity in text and version in text, name
+        assert text.count('```') % 2 == 0, name
+    print(identity + '@' + version)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/tools/gen_sources.py b/tools/gen_sources.py
index b616580..6e34689 100755
--- a/tools/gen_sources.py
+++ b/tools/gen_sources.py
@@ -84,6 +84,7 @@ def collect(grpc_root: pathlib.Path) -> tuple[list[str], list[str]]:
     "    # of a `kind = \"lib\"` package as src/<package tail>.cppm, so this file\n"
     "    # is both the module and what satisfies that convention.\n"
     '    "src/grpc.cppm",\n'
+    '    "src/macros.cppm",\n'
 )
 
 
diff --git a/tools/test_template.py b/tools/test_template.py
new file mode 100644
index 0000000..81ea805
--- /dev/null
+++ b/tools/test_template.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Render an installed candidate's default mcpp template, then build and run it."""
+import argparse
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+import tomllib
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--mcpp", default="mcpp")
+    parser.add_argument("--namespace", help="index namespace for legacy manifests without package.namespace")
+    parser.add_argument("--toolchain", default="llvm@23.1.3")
+    parser.add_argument("--template", help="named template; omit for the package default")
+    parser.add_argument("--run-arg", action="append", default=[])
+    parser.add_argument("--index", type=Path, help="candidate SDK/wrapper index for unpublished feature dependencies")
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parents[1]
+    metadata = tomllib.loads((root / "mcpp.toml").read_text())["package"]
+    namespace = metadata.get("namespace", args.namespace)
+    assert namespace, "Supply the published index namespace for this legacy manifest"
+    name, version = metadata["name"], metadata["version"]
+    identity = namespace + "." + name
+    with tempfile.TemporaryDirectory(prefix=name + "-template-") as directory:
+        temporary = Path(directory)
+        home = temporary / "home"
+        package = home / "registry/data/xpkgs" / (namespace + "-x-" + name) / version / (name + "-" + version)
+        shutil.copytree(root, package, ignore=shutil.ignore_patterns(
+            ".git", "target", ".mcpp", ".xlings", ".candidate-index", "__pycache__", "mcpp.lock", "compile_commands.json", "mcpp-2026.*"))
+        index = home / "indices/mcpplibs/pkgs/mwrap"
+        index.mkdir(parents=True)
+        entry = '{url="https://example.invalid/candidate.tar.gz",sha256="fixture"}'
+        descriptor = ('package={spec="1",namespace=' + json.dumps(namespace) + ',name=' + json.dumps(name) +
+                      ',description="Installed template fixture",type="package",mcpp="mcpp.toml",xpm={')
+        descriptor += ",".join(platform + "={[" + json.dumps(version) + "]=" + entry + "}"
+                               for platform in ("linux", "macosx", "windows")) + "}}\n"
+        (index / (identity + ".lua")).write_text(descriptor)
+        env = dict(os.environ, MCPP_HOME=str(home))
+        selector = identity + "@" + version
+        for command in ([args.mcpp, "new", "--list-templates", selector],
+                        [args.mcpp, "new", "quickstart", "--template", selector + (":" + args.template if args.template else "")]):
+            print("+", " ".join(command), flush=True)
+            subprocess.run(command, cwd=temporary, env=env, check=True)
+        project = temporary / "quickstart"
+        manifest = project / "mcpp.toml"
+        text = manifest.read_text()
+        dependency = tomllib.loads(text)["dependencies"][identity]
+        options = {"version": dependency} if isinstance(dependency, str) else dependency
+        assert options["version"] == version, options
+        replacement = '{ path = ' + json.dumps(package.as_posix())
+        if options.get("features"):
+            replacement += ', features = ' + json.dumps(options["features"])
+        replacement += ' }'
+        lines = text.splitlines()
+        matches = [i for i, line in enumerate(lines) if line.startswith(json.dumps(identity) + " =")]
+        assert len(matches) == 1, "Expected exactly one qualified dependency from self.name"
+        lines[matches[0]] = json.dumps(identity) + " = " + replacement
+        manifest.write_text("\n".join(lines) + "\n")
+        if args.index:
+            candidate_index = args.index.resolve()
+            subprocess.run([os.sys.executable, str(candidate_index / "tests/prepare_mwrap_indices.py")],
+                           cwd=candidate_index, check=True)
+            with manifest.open("a") as out:
+                out.write("\n[indices]\n")
+                for namespace in ("compat", "mcpplibs.mwrap"):
+                    view = candidate_index / "tests/mwrap/.indices" / namespace
+                    out.write(json.dumps(namespace) + ' = { path = ' + json.dumps(view.as_posix()) + ' }\n')
+        command = [args.mcpp, "build", "--toolchain", args.toolchain, "--strict"]
+        print("+", " ".join(command), flush=True)
+        subprocess.run(command, cwd=project, check=True)
+        command = [args.mcpp, "run", "--toolchain", args.toolchain]
+        if args.run_arg:
+            command += ["--", *args.run_arg]
+        print("+", " ".join(command), flush=True)
+        subprocess.run(command, cwd=project, check=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/upstream/documents.json b/upstream/documents.json
new file mode 100644
index 0000000..37ffbcc
--- /dev/null
+++ b/upstream/documents.json
@@ -0,0 +1,15 @@
+{
+  "upstream": "https://github.com/grpc/grpc/tree/v1.83.0",
+  "documents": [
+    {
+      "path": "upstream/grpc/README.md",
+      "source": "https://github.com/grpc/grpc/tree/v1.83.0/README.md",
+      "sha256": "15823e28dd6dcadfba187ac188bf22d79f26b783d1813eaca58588dbd2781d4f"
+    },
+    {
+      "path": "upstream/grpc/LICENSE",
+      "source": "https://github.com/grpc/grpc/tree/v1.83.0/LICENSE",
+      "sha256": "58c86a3f2b5cca0ebdf9ed3e7f4e6dc38e3b38796d8c3dc92064c62a4e39d0dd"
+    }
+  ]
+}
diff --git a/upstream/grpc/LICENSE b/upstream/grpc/LICENSE
new file mode 100644
index 0000000..9835265
--- /dev/null
+++ b/upstream/grpc/LICENSE
@@ -0,0 +1,623 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+-----------------------------------------------------------
+
+Following applies to:
+./src/objective-c/!ProtoCompiler-gRPCCppPlugin.podspec
+./src/objective-c/!ProtoCompiler-gRPCPlugin.podspec
+./src/objective-c/!ProtoCompiler.podspec
+./src/objective-c/BoringSSL-GRPC.podspec
+./templates/src/objective-c/!ProtoCompiler-gRPCCppPlugin.podspec.inja
+./templates/src/objective-c/!ProtoCompiler-gRPCPlugin.podspec.inja
+./templates/src/objective-c/!ProtoCompiler.podspec.inja
+./templates/src/objective-c/BoringSSL-GRPC.podspec.template
+
+BSD 3-Clause License
+
+Copyright 2016, Google Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.
+
+-----------------------------------------------------------
+
+Following applies to:
+./etc/roots.pem
+
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.
diff --git a/upstream/grpc/README.md b/upstream/grpc/README.md
new file mode 100644
index 0000000..f7b8a47
--- /dev/null
+++ b/upstream/grpc/README.md
@@ -0,0 +1,105 @@
+# gRPC – An RPC library and framework
+
+gRPC is a modern, open source, high-performance remote procedure call (RPC)
+framework that can run anywhere. gRPC enables client and server applications to
+communicate transparently, and simplifies the building of connected systems.
+
+<table>
+  <tr>
+    <td><b>Homepage:</b></td>
+    <td><a href="https://grpc.io/">grpc.io</a></td>
+  </tr>
+  <tr>
+    <td><b>Mailing List:</b></td>
+    <td><a href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io@googlegroups.com</a></td>
+  </tr>
+</table>
+
+[![Join the chat at https://gitter.im/grpc/grpc](https://badges.gitter.im/grpc/grpc.svg)](https://gitter.im/grpc/grpc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+## To start using gRPC
+
+To maximize usability, gRPC supports the standard method for adding dependencies
+to a user's chosen language (if there is one). In most languages, the gRPC
+runtime comes as a package available in a user's language package manager.
+
+For instructions on how to use the language-specific gRPC runtime for a project,
+please refer to these documents
+
+-   [C++](src/cpp): follow the instructions under the `src/cpp` directory
+-   [C#/.NET](https://github.com/grpc/grpc-dotnet): NuGet packages
+    `Grpc.Net.Client`, `Grpc.AspNetCore.Server`
+-   [Dart](https://github.com/grpc/grpc-dart): pub package `grpc`
+-   [Go](https://github.com/grpc/grpc-go): `go get google.golang.org/grpc`
+-   [Java](https://github.com/grpc/grpc-java): Use JARs from Maven Central
+    Repository
+-   [Kotlin](https://github.com/grpc/grpc-kotlin): Use JARs from Maven Central
+    Repository
+-   [Node](https://github.com/grpc/grpc-node): `npm install @grpc/grpc-js`
+-   [Objective-C](src/objective-c): Add `gRPC-ProtoRPC` dependency to podspec
+-   [PHP](src/php): `pecl install grpc`
+-   [Python](src/python/grpcio): `pip install grpcio`
+-   [Ruby](src/ruby): `gem install grpc`
+-   [WebJS](https://github.com/grpc/grpc-web): follow the grpc-web instructions
+
+Per-language quickstart guides and tutorials can be found in the
+[documentation section on the grpc.io website](https://grpc.io/docs/). Code
+examples are available in the [examples](examples) directory.
+
+Precompiled bleeding-edge package builds of gRPC `master` branch's `HEAD` are
+uploaded daily to [packages.grpc.io](https://packages.grpc.io).
+
+## To start developing gRPC
+
+Contributions are welcome!
+
+Please read [How to contribute](CONTRIBUTING.md) which will guide you through
+the entire workflow of how to build the source code, how to run the tests, and
+how to contribute changes to the gRPC codebase. For detailed C++ build instructions,
+see [Building from source](BUILDING.md). The "How to contribute" document
+also contains info on how the contribution process works and contains best
+practices for creating contributions.
+
+## Troubleshooting
+
+Sometimes things go wrong. Please check out the
+[Troubleshooting guide](TROUBLESHOOTING.md) if you are experiencing issues with
+gRPC.
+
+## Performance
+
+See the [Performance dashboard](https://grafana-dot-grpc-testing.appspot.com/)
+for performance numbers of master branch daily builds.
+
+## Concepts
+
+See [gRPC Concepts](CONCEPTS.md)
+
+## About This Repository
+
+This repository contains source code for gRPC libraries implemented in multiple
+languages written on top of a shared C++ core library [src/core](src/core).
+
+Libraries in different languages may be in various states of development. We are
+seeking contributions for all of these libraries:
+
+Language                  | Source
+------------------------- | ----------------------------------
+Shared C++ [core library] | [src/core](src/core)
+C++                       | [src/cpp](src/cpp)
+Ruby                      | [src/ruby](src/ruby)
+Python                    | [src/python](src/python)
+PHP                       | [src/php](src/php)
+C# (core library based)   | [src/csharp](src/csharp)
+Objective-C               | [src/objective-c](src/objective-c)
+
+Language             | Source repo
+-------------------- | --------------------------------------------------
+Java                 | [grpc-java](https://github.com/grpc/grpc-java)
+Kotlin               | [grpc-kotlin](https://github.com/grpc/grpc-kotlin)
+Go                   | [grpc-go](https://github.com/grpc/grpc-go)
+NodeJS               | [grpc-node](https://github.com/grpc/grpc-node)
+WebJS                | [grpc-web](https://github.com/grpc/grpc-web)
+Dart                 | [grpc-dart](https://github.com/grpc/grpc-dart)
+.NET (pure C# impl.) | [grpc-dotnet](https://github.com/grpc/grpc-dotnet)
+Swift                | [grpc-swift](https://github.com/grpc/grpc-swift)