@@ -62,6 +62,33 @@ library reaches things only the session has.
 session satisfies the protocol too — `ctx.__datafusion_query_planner__()` and
 `ctx.__datafusion_query_planner__(ctx)` are both valid.
 
+`__datafusion_session_planner__(ctx, fallback)` is the exception to the shape
+above: it takes a second argument, the planner assembled so far. A session has
+one planner slot, so planners compose by nesting rather than by chaining, and
+the host hands each bundle the previous layer instead of letting it capture one.
+Wrap `fallback` and delegate to it; returning a planner that ignores it discards
+every layer beneath, including one the session already had. It runs after every
+bundle's codecs are installed, so `ctx` carries the final chains.
+
+That is also the only hook where it does. `__datafusion_session_components__`
+runs before anything is installed, so its `ctx` still carries the chains the
+receiver had — the same session, and the same task-context provider, but not
+this call's codecs, not even your own. Read the host's codec chains in the
+planner hook, never in the extension hook.
+
+A *codec* must always be handed over as an object implementing its getter, never
+as the bare capsule the getter returns; `with_extensions` refuses a capsule.
+A codec's wire id — the string a payload names on decode, which has to mean the
+same thing in whichever process decodes — is read off the object it arrives as,
+and a capsule has no type to read one from. Deriving the id from the bundle that
+contributed the capsule is not the fix: the bundle is whatever object the caller
+passed, so an application packaging your library inside a bundle of its own
+would re-tag your payloads and they would stop decoding where they are read. If
+the object's class name is not the identity you want on the wire, declare
+`__datafusion_codec_id__` on it. `BundledLogicalCodec` in
+`examples/datafusion-ffi-query-planner-example/src/extension.rs` is the shape.
+This applies only to codecs — a query planner carries no wire id.
+
 ## Rule 3 — never construct a `SessionContext` in an extension library
 
 The FFI constructors ask for things a library does not have:
@@ -154,8 +181,19 @@ guards this. Its `WHERE` clause is load-bearing: filter pushdown upgrades the
 weak handle during logical optimization, before plan serialization could fail
 first for an unrelated reason.
 
+`SessionContext.with_extensions` is where this rule is easiest to get wrong,
+because "bind the components to the context you are about to return" reads like
+an instruction to derive one first. It is not: the factories are handed the
+receiver, and the returned handle shares its allocation. There is nothing to
+keep alive separately and nothing to garbage-collect out from under a provider.
+
 `SessionContext.enable_url_table` is the one method that mints a second
-allocation for a session. Its result must not outlive the receiver.
+allocation for a session. Its result must not outlive the receiver, and it also
+forks the session's `SessionState` while keeping its id, so two handles report
+one `session_id()` with divergent configuration. That is a bug rather than a
+design — tracked in
+[apache/datafusion-python#1708](https://github.com/apache/datafusion-python/issues/1708)
+— so do not cite it as precedent for deriving a replacement context.
 
 ## Rule 7 — installing a planner mutates the session, and says so
 
@@ -185,7 +223,12 @@ pins that; changing it should be deliberate.
 
 ## Where the truth is
 
-- `docs/source/contributor-guide/ffi.md` — the protocol, the fork caveat.
+- `docs/source/extension-guide/` — the protocol, for the library author.
+  `capsule-protocol.md` has the hook convention and what the getter argument
+  actually is; `codecs.md`, `bundles.md`, and `query-planners.md` have the
+  per-component rules; `index.md` lists all 18 hooks.
+- `docs/source/contributor-guide/ffi-internals.md` — why the framing is shaped
+  this way, including the weak-`Arc` scheme and the one-level rebind.
 - `docs/source/user-guide/upgrade-guides.md` — every past migration.
 - `crates/core/src/codec.rs` — the codec chain: the envelope, identity dispatch,
   and the two unframed cases from Rule 8.
 
@@ -45,7 +45,7 @@ jobs:
   lint-rust:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4
@@ -62,14 +62,14 @@ jobs:
   lint-python:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
@@ -88,10 +88,10 @@ jobs:
   lint-toml:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install taplo
-        uses: taiki-e/install-action@v2
+        uses: taiki-e/install-action@v2.85.5
         with:
           tool: taplo-cli
 
@@ -103,22 +103,22 @@ jobs:
     if: inputs.build_mode == 'release' && startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Ensure [patch.crates-io] is empty
         run: python3 dev/check_crates_patch.py
 
   generate-license:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
       - name: Install cargo-license
-        uses: taiki-e/install-action@v2
+        uses: taiki-e/install-action@v2.85.5
         with:
           tool: cargo-license
 
@@ -142,7 +142,7 @@ jobs:
       matrix:
         python-tag: ["abi3", "3.14t"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - run: rm LICENSE.txt
       - name: Download LICENSE.txt
@@ -159,7 +159,7 @@ jobs:
         with:
           key: ${{ inputs.build_mode }}-${{ matrix.python-tag }}
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
@@ -233,7 +233,7 @@ jobs:
       matrix:
         python-tag: ["abi3", "3.14t"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - run: rm LICENSE.txt
       - name: Download LICENSE.txt
@@ -250,7 +250,7 @@ jobs:
         with:
           key: ${{ inputs.build_mode }}-${{ matrix.python-tag }}
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
@@ -296,7 +296,7 @@ jobs:
         os: [macos-latest, windows-latest]
         python-tag: ["abi3", "3.14t"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4
@@ -315,12 +315,12 @@ jobs:
 
       - name: Setup Python (free-threaded)
         if: matrix.python-tag != 'abi3'
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-tag }}
           freethreaded: true
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
@@ -379,7 +379,7 @@ jobs:
       matrix:
         python-tag: ["abi3", "3.14t"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4
@@ -398,12 +398,12 @@ jobs:
 
       - name: Setup Python (free-threaded)
         if: matrix.python-tag != 'abi3'
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-tag }}
           freethreaded: true
 
-      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
@@ -444,7 +444,7 @@ jobs:
     if: inputs.build_mode == 'release'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - run: rm LICENSE.txt
       - name: Download LICENSE.txt
         uses: actions/download-artifact@v8
@@ -516,23 +516,23 @@ jobs:
           fi
 
       - name: Checkout docs sources
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Checkout docs target branch
         if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref_type == 'tag')
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           ref: ${{ steps.target-branch.outputs.value }}
           path: docs-target
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: "3.10"
 
       - name: Install dependencies
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
 
@@ -39,16 +39,16 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       with:
         persist-credentials: false
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
+      uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
       with:
         languages: actions
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
+      uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
       with:
         category: "/language:actions"
@@ -30,9 +30,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: "3.14"
       - name: Audit licenses
 
@@ -46,23 +46,23 @@ jobs:
           # Free-threaded builds — one wheel per interpreter.
           - { python-version: "3.14t", wheel-tag: "3.14t", freethreaded: true }
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Python
         id: setup-python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           freethreaded: ${{ matrix.freethreaded }}
 
       - name: Cache Cargo
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.cargo
           key: cargo-cache-stable-${{ hashFiles('Cargo.lock') }}
 
       - name: Install dependencies
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d
         with:
           enable-cache: true
 
 
@@ -65,7 +65,7 @@ jobs:
     runs-on: ${{ matrix.runner }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up protoc
         uses: arduino/setup-protoc@v3
 
@@ -133,6 +133,47 @@ Every Python function must include a docstring with usage examples.
   `array_sort`) only need a one-line description and a `See Also` reference to the
   primary function. They do not need their own examples.
 
+### One canonical home per claim
+
+A claim lives where the reader already is when they need it — **exactly once**.
+
+- A property of one callable's arguments, return value, or errors → that
+  callable's docstring.
+- A property of a *type* that several callables share → the class docstring.
+  (Session sharing and context lifetime live on `SessionContext`, not on each
+  of the five `with_*` methods.)
+- **Why** the API is shaped this way, a multi-library recipe, Rust-side code, a
+  trade-off, or a limitation with an upstream issue → the narrative guide under
+  `docs/source/`.
+
+Everywhere else: one sentence plus one Sphinx role. A docstring may *state* a
+claim the guide also makes; it must not *argue* it — no "because", no "the
+reason is", no counter-argument.
+
+**The test:** if a paragraph would survive being moved into the guide unchanged,
+move it. `python/tests/test_docstrings.py` enforces a length ceiling, which is
+the symptom this rule treats.
+
+When you point at the guide, use a real `:ref:` to a specific label. Prose
+saying "see the extensions guide" with no role is a dead end in the rendered
+HTML.
+
+### Examples that need a compiled extension
+
+Some APIs cannot be demonstrated without a built FFI extension library, which
+this package does not ship. The convention is:
+
+1. A **runnable** example block first, using only the wheel. A `SessionContext`
+   satisfies the capsule-getter protocols, so its own exported capsule stands in
+   for a real library's in a doctest.
+2. Then a `# doctest: +SKIP` block showing real usage, at most a few lines, with
+   one line of prose naming the test that runs it for real.
+3. Every `+SKIP` block needs that mirror. See
+   `test_with_extensions_docstring_example_still_runs` in
+   `examples/datafusion-ffi-query-planner-example`, which parses the live
+   docstring, drops the skip, and executes it — so a renamed method or a wrong
+   expected output fails there.
+
 ## Aggregate and Window Function Documentation
 
 When adding or updating an aggregate or window function, ensure the corresponding