update linking realted logic

- remove post-commit hook
 - remove .links.cjs enable/disable (instead just add/rm .pnpmfile.cjs)
 - rename pnpm links:enable -> pnpm links:on
 - rename pnpm links:disable -> pnpm links:off
 - unify doc filenames `-` -> `_`
 - add linking_concept_reasoning.md to provide background why the
   linking is how it is.

scripts/.pnpmfile.cjs

@@ -0,0 +1,62 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+// DONT RUN THIS FILE MANUALLY
+// This file is intended to be used with `pnpm links:on` and `pnpm links:off` which will copy this file to the project root.
+// See docs/linking.md for details.
+//
+//
+// Created based on https://github.com/element-hq/element-call/blob/60fae70a60e3697eb41210ccf1e400cab37df7c8/.yarn/plugins/linker.cjs
+// and the following prompt history:
+// - Can you convert this yarn plugin into a pnpm plugin.
+// - The goal is to not have modifications to the package.json and lock files so that we do not track links on gh.
+// This seems to modify the package.json file.
+// What can we do with pnpm to have the link inforamtion in a seperate file
+// - why do you cache the loaded links. When does this file get executed?
+// Do we need this optimization.
+// How do we guarantee, that we aleays use the most recent content from the links file?
+//
+// Manual transition to cjs. Claude proposed manual yaml parsing.
+
+const fs = require("fs");
+const path = require("path");
+
+function loadLinks() {
+  try {
+    return require(path.join(__dirname, ".links.cjs"));
+  } catch (e) {
+    return null;
+  }
+}
+
+function readPackage(pkg, context) {
+  const links = loadLinks();
+  if (!links) return pkg;
+
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "package.json"), "utf8"),
+  );
+  if (pkg.name !== manifest.name) return pkg;
+
+  for (const [name, linkPath] of Object.entries(links)) {
+    const resolved = `link:${path.resolve(__dirname, linkPath)}`;
+    if (pkg.dependencies && pkg.dependencies[name]) {
+      context.log(`Linking ${name} -> ${resolved}`);
+      pkg.dependencies[name] = resolved;
+    } else if (pkg.devDependencies && pkg.devDependencies[name]) {
+      context.log(`Linking ${name} -> ${resolved}`);
+      pkg.devDependencies[name] = resolved;
+    }
+  }
+
+  return pkg;
+}
+
+module.exports = {
+  hooks: {
+    readPackage,
+  },
+};

scripts/setup-linking.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+# Checks if there currently is linking configured. Informs the user to disable linking before committing.
+
+LINKSFILE=.links.cjs
+echo "Checking for existing linking configuration in $LINKSFILE..."
+if test -f "$LINKSFILE"; then
+echo "Linking configuration found in $LINKSFILE."
+else
+    echo "No $LINKSFILE -> Creating $LINKSFILE with default values. Please edit this file to point to your local checkouts of the dependencies you want to link."
+    echo '''// Packages to link to local checkouts
+module.exports = {
+    "matrix-js-sdk": "../your/path/matrix-js-sdk",
+    "matrix-widget-api": "../your/path/matrix-widget-api",
+};''' > $LINKSFILE
+fi
+echo "updating local git hookPath to .githooks"
+git config --local core.hooksPath .githooks
+echo ""
+echo "Setup complete."
+echo "Update: .links.cjs to your liking"
+echo "Run: 'pnpm links:on' to test your .links.cjs"
+echo "Run: 'git commit' with links enabled to test the git pre-commit hook."
+echo "Run: 'pnpm links:off' to be able to commit again"
+echo "Run: 'git config --local core.hooksPath \"\"' to allow committing with linking on (not recommended)"
+echo "Run: 'rm links.cjs' & 'git config --local core.hooksPath \"\"' to fully revert what this script did"