machine-bridge-mcp 0.16.2 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.17.1 - 2026-07-14
+
+### Installation and first use
+
+- Add an end-to-end installation and first-use guide covering transport selection, authority profiles, prerequisites, released and source installation, first remote deployment, current ChatGPT developer-mode connection, stdio configuration, existing-profile browser pairing, verification, routine operation, multi-workspace use, upgrades, layered troubleshooting, and fail-closed removal.
+- Link the detailed guide from the README while retaining the compact command reference, and clarify how to distinguish package, Cloudflare, daemon, MCP-host, operating-system, and browser failures.
+
+### Multi-client and multi-account boundary
+
+- Document that the existing Worker supports multiple OAuth client registrations and access tokens but does not provide isolated human/service accounts: all successful authorizations use one per-workspace connection password and share the same policy and daemon authority.
+- Define a principal-aware evolution path that keeps OAuth clients separate from principals, memberships, and named grants; uses capability intersection and dual Worker/local enforcement; adds targeted revocation and per-principal quotas; and retains one bridge/Durable Object per workspace or trust domain.
+- Make the security and architecture contracts explicit: mutually untrusted users require separate bridge instances and preferably separate low-privilege OS, container, or VM boundaries because application-level roles cannot isolate local process, shell, browser, or credential-store authority.
+
+## 0.17.0 - 2026-07-13
+
+### Project governance and contribution flow
+
+- Define a risk-based project standard covering GitHub Flow, Conventional Commits, architecture boundaries, MCP contract ownership, testing, errors, logging, supply-chain security, documentation, review, and explicit exceptions. Add pull-request and structured issue templates plus area ownership through CODEOWNERS.
+- Add an executable Conventional Commit policy for pull-request and main-branch commit titles. Keep the repository on squash-based GitHub Flow rather than introducing permanent develop/release branches that do not match its single-maintainer, continuously released operating model.
+- Require all repository-host operations to use local `git`, `gh`, and `gh api` through Machine Bridge. Explicitly prohibit hosted GitHub connectors or ChatGPT GitHub plugins so remote mutations, credentials, refs, checks, and recovery remain observable from one local control plane.
+- Make repository automation responsible for closing the source-change lifecycle: after all required checks pass it squash-merges the pull request, verifies `main`, creates and pushes the annotated version tag, and creates or updates the matching GitHub Release. npm publication, Worker deployment, credentials, global installation, and daemon/service replacement remain separately authorized live operations.
+
+### Generated contracts and security automation
+
+- Generate a complete MCP tool reference from the shared tool catalog and reject stale output in the required suite. The tool catalog remains the single source for names, availability, annotations, and JSON input schemas; REST-specific Swagger documentation is not duplicated for the MCP surface.
+- Add pinned, least-privilege GitHub workflows for CodeQL analysis, pull-request dependency review, OpenSSF Scorecard publication, and governance checks. Preserve exact dependency versions, registry signature/attestation verification, SBOM generation, history privacy scanning, and cross-platform package tests.
+
+### Cohesion, reuse, and runtime reliability
+
+- Extract optional project-metadata reads, strict integer normalization, plain-record validation, and uninstall/service state inventory into focused shared modules. Remove duplicate numeric clamping, record classification, and no-follow UTF-8 metadata readers while preserving the distinct strict validation semantics used by browser/application commands and Agent Context instruction files. Plain-record validation now rejects class instances instead of treating every non-array object as protocol/configuration data.
+- Reduce the CLI entrypoint from 1,169 to 1,063 lines by moving profile, Worker, active-job, and process-lock inventory behind a dedicated boundary. Add direct failure-path tests and enforce 91% function/73% branch coverage for the new inventory module; raise the CLI branch floor from 5% to 10%.
+- Canonicalize existing state roots before profile enumeration, fixing macOS `/var` versus `/private/var` alias mismatches that could make service removal or lock inspection report inconsistent profile paths. Retry only the final daemon-lock handoff after a verified service stop, and keep daemon fixture subprocesses out of V8 coverage so process teardown does not create platform-timing failures.
+- Generate Wrangler environment declarations through a cross-platform script that creates ignored `.wrangler/` state before invoking Wrangler, instead of writing under `src/worker`; packaging tests reject generated type declarations. This removes clean-runner state dependence and reduces the dry-run package from about 410 KB/1.8 MB unpacked to about 314 KB/1.22 MB while retaining every Worker runtime module.
+- Replace repeated empty WebSocket send/close catches in the Worker and browser extension with small module-local best-effort helpers whose comments preserve the primary failure semantics. Architecture checks reject unexplained empty catches on those protocol boundaries.
+
+### Tests and documentation
+
+- Extend architecture checks to require generated tool documentation, governance scripts, security workflows, explicit workflow permissions, immutable Action references, and rejection of privileged pull-request triggers or write-all permissions.
+- Document why aggregate 80% coverage is not a sufficient quality target, identify the current CLI orchestration branch-coverage weakness, and retain per-module risk thresholds plus behavior-level cross-platform, concurrency, fault-injection, and protocol tests.
+
 ## 0.16.2 - 2026-07-13
 
 ### Fixed

package/CONTRIBUTING.md

@@ -2,6 +2,20 @@
 
 This repository treats every Git-tracked or nonignored repository file as release-relevant, including source code, tests, scripts, examples, documentation, CI configuration, ignore rules, and package metadata.
 
+## Development workflow
+
+Read [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md) and the relevant domain documentation before changing behavior. This repository uses GitHub Flow: branch from current `main`, keep the change coherent, open a pull request, satisfy required checks, squash-merge, and delete the branch. Permanent `develop` or generic release integration branches are not used unless an independently maintained release line creates a concrete need. Repository automation performs GitHub operations only through local `git`, `gh`, and `gh api` commands executed by Machine Bridge; hosted GitHub connectors and ChatGPT GitHub plugins are prohibited for this repository.
+
+Branch names use a category and purpose such as `feat/browser-downloads`, `fix/relay-timeout`, or `chore/dependency-policy`.
+
+Pull-request titles and final commit subjects use Conventional Commits:
+
+```text
+<type>[optional scope][optional !]: <imperative description>
+```
+
+Accepted types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. Explain the causal problem, why the solution is correct, compatibility/security/privacy risk, verification, and release impact in the pull request. Bug fixes require a regression test for the original failure mechanism.
+
 ## Required for every release-relevant change
 
 Before the reviewed code is pushed to `main`:

package/README.md

@@ -23,6 +23,8 @@ Local clients such as Claude Desktop, Cursor, and Codex CLI
 
 The remote Worker authenticates and relays calls. It cannot directly read local files or start local processes. File, Git, image, patch, process, diagnostic, and managed-job operations execute in the local runtime.
 
+New users should follow the end-to-end [installation and first-use guide](docs/GETTING_STARTED.md). Before sharing a deployment or connecting several accounts, read [multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md).
+
 ## Default behavior and policy profiles
 
 A newly selected workspace starts with the maximum-permission `full` profile for low-friction operation:
@@ -45,6 +47,8 @@ This default prioritizes usability, not least privilege. `run_process` and proce
 
 ## Install
 
+For prerequisites, first remote deployment, ChatGPT connection, stdio configuration, browser pairing, upgrades, troubleshooting, and removal, follow [Installation and first use](docs/GETTING_STARTED.md). The commands below are the compact installation reference.
+
 Node.js 26 or newer and npm 12 or newer are required. The repository pins the active development versions in `.node-version`, `.nvmrc`, and `packageManager`; project installs fail on older Node runtimes.
 
 Use a new temporary directory for the bootstrap. The existing `npm`/`npx` front-end may inspect nearby project metadata before it launches the requested npm version; starting from an empty directory prevents an unrelated legacy `devEngines` declaration from blocking the bootstrap. The actual installation is then executed by the pinned npm 12 CLI rather than whichever npm happens to be first on `PATH`.
@@ -126,6 +130,12 @@ MCP connection password: mcp_password_...
 
 The remote authorization flow uses an authorization code, PKCE S256, exact redirect/resource binding, expiring access tokens stored as hashes, and a token-version value for bulk revocation. After password approval, the Worker constructs the registered callback with the URL API and returns `303 See Other`, so OAuth response parameters are encoded and the browser performs a GET to the callback.
 
+### Multiple clients and accounts
+
+One Worker can hold several OAuth client registrations and access tokens, so the same trusted owner or team can connect more than one MCP application or ChatGPT account. This is **multi-client access, not isolated multi-account tenancy**: the current release uses one workspace connection password, one workspace policy, and one active daemon authority. It has no principal records, per-account roles, targeted account revocation, or account-specific audit boundary.
+
+Do not share a `full` bridge with mutually untrusted users. Use a separate bridge and preferably a separate low-privilege OS account, container, or VM for each trust domain. See [Multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md) for the current support matrix and the proposed principal/grant design.
+
 ## Optional local stdio MCP
 
 stdio is a local transport, not a model provider. Claude Desktop, Cursor, Codex CLI, ChatGPT Desktop, or another MCP host supplies its own model/session and launches `machine-bridge-mcp` as a subprocess. The MCP server only exposes tools and returns their results; it does not borrow the model running in ChatGPT web.
@@ -480,7 +490,7 @@ npm pack --dry-run
 
 `npm run check` covers privacy and release-impact gates, architecture/link invariants, generated Worker types, TypeScript, recursively discovered JavaScript syntax, catalog-to-runtime handler parity, deterministic relay lifecycle and secure-file tests, concurrent lock/atomic-replacement/PID-reuse fixtures, fail-closed service lifecycle tests, descendant process-tree termination, local path/write/state/log/service invariants, Ed25519/RSA generation and key-pair validation, real-machine `full` sandbox acceptance, a clean npm package-manifest/mode/sensitive-artifact check, managed-job integrity/redaction/finally/cancellation/recovery, a live stdio MCP flow, and a live local OAuth/Worker/WebSocket/MCP flow. GitHub Actions runs the suite on Linux, macOS, and Windows with the pinned Node 26/npm 12 baseline; macOS and package-audit jobs also exercise the documented isolated global installation.
 
-The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), and [SECURITY.md](SECURITY.md).
+The cross-cutting 0.12.0 review, corrected failure modes, and residual OS-level limits are recorded in [docs/AUDIT.md](docs/AUDIT.md). See also [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md), [docs/MULTI_ACCOUNT.md](docs/MULTI_ACCOUNT.md), [docs/AGENT_CONTEXT.md](docs/AGENT_CONTEXT.md), [docs/LOCAL_AUTOMATION.md](docs/LOCAL_AUTOMATION.md), [docs/MANAGED_JOBS.md](docs/MANAGED_JOBS.md), [docs/TESTING.md](docs/TESTING.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/ENGINEERING.md](docs/ENGINEERING.md), [docs/PROJECT_STANDARDS.md](docs/PROJECT_STANDARDS.md), the generated [MCP tool reference](docs/TOOL_REFERENCE.md), and [SECURITY.md](SECURITY.md).
 
 ## Uninstall
 

package/SECURITY.md

@@ -36,6 +36,14 @@ An authorized client can invoke every tool exposed by the selected profile and r
 
 The Worker is a remote authentication and relay boundary. The local runtime is the filesystem and process boundary. Stdio bypasses the Worker and relies on local process/configuration trust.
 
+### Multiple clients are not isolated accounts
+
+The current remote design accepts multiple OAuth client registrations and can issue multiple access tokens, but it has one per-workspace connection password and one workspace policy. An OAuth `client_id` identifies client software and redirect URIs; it is not a human or service principal. Different ChatGPT accounts or MCP applications that authorize with the same password therefore enter the same trust domain and receive the same Machine Bridge authority.
+
+The current release has no per-account role, suspension, membership expiry, targeted principal revocation, or account-specific audit boundary. Secret rotation invalidates all outstanding access tokens for the workspace. Do not present this behavior as multi-user tenancy.
+
+Mutually untrusted users must use separate bridge instances and external isolation appropriate to the authority exposed: a dedicated low-privilege OS account, container, or VM, a narrow workspace, an independent state root and Worker credential set, and the narrowest useful profile. Worker-side account records alone cannot isolate direct processes, shells, browser sessions, Accessibility actions, credential stores, or network authority inherited from the local OS user. See [Multi-client, multi-account, and tenancy architecture](docs/MULTI_ACCOUNT.md).
+
 ## Profiles are capability sets, not sandboxes
 
 The default for newly selected workspaces is `full`, which prioritizes ease of use over least privilege. Named profiles are canonical capability contracts. A stored `full` label is repaired on load to the complete maximum-permission field set and tool catalog; a deliberate per-capability override is represented as `custom`, not as a partially restricted `full`.
@@ -152,7 +160,7 @@ Runner diagnostic logs are owner-only and do not receive child stdout/stderr. St
 
 ## OAuth and public endpoints
 
-Remote mode uses authorization code flow with PKCE S256, exact redirect/resource/client binding, expiring authorization codes and access tokens, hashed token storage, token-version revocation, and bounded dynamic client registration. Successful consent constructs the registered callback through the URL API and returns `303 See Other`; response parameters are encoded rather than concatenated into an unchecked header string.
+Remote mode uses authorization code flow with PKCE S256, exact redirect/resource/client binding, expiring authorization codes and access tokens, hashed token storage, token-version revocation, and bounded dynamic client registration. Client registrations and tokens may coexist, but all authorizations currently share one workspace credential and authority; there is no principal-aware account model. Successful consent constructs the registered callback through the URL API and returns `303 See Other`; response parameters are encoded rather than concatenated into an unchecked header string.
 
 The authorization page displays the validated client name and redirect URI. Enter the connection password only after initiating the connection and recognizing both values.
 

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.16.2"
+  "version_name": "0.17.1"
 }

package/browser-extension/service-worker.js

@@ -67,12 +67,33 @@ function setConnectionState(state) {
       : state === "unconfigured"
         ? "Machine Bridge Browser: click to open pairing"
         : "Machine Bridge Browser: disconnected; click to open pairing";
-  try { ignoreOptionalPromise(chrome.action.setBadgeText({ text: badge })); } catch {}
-  try { ignoreOptionalPromise(chrome.action.setTitle({ title })); } catch {}
+  ignoreBrowserApiCall(() => chrome.action.setBadgeText({ text: badge }));
+  ignoreBrowserApiCall(() => chrome.action.setTitle({ title }));
 }
 
-function ignoreOptionalPromise(value) {
-  if (value && typeof value.catch === "function") value.catch(() => {});
+function ignoreBrowserApiCall(operation) {
+  try {
+    const value = operation();
+    if (value && typeof value.catch === "function") value.catch(() => {});
+  } catch {
+    // Browser UI decoration is optional and must not disrupt broker connectivity.
+  }
+}
+
+function closeSocketQuietly(ws, code, reason) {
+  try {
+    ws?.close(code, reason);
+  } catch {
+    // The socket may already be closed; reconnect state remains authoritative.
+  }
+}
+
+function sendSocketQuietly(ws, payload) {
+  try {
+    ws.send(payload);
+  } catch {
+    // A response cannot be recovered after the broker socket closes.
+  }
 }
 
 async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl }) {
@@ -119,27 +140,29 @@ async function confirmRepairFromTab(tab) {
       }),
     });
     const paired = await pairConfiguration(result?.result?.endpoint, result?.result?.token, { replace: true, senderUrl: tab.url });
-    await chrome.scripting.executeScript({
-      target: { tabId: tab.id },
-      func: (ok) => {
-        const status = document.getElementById("status");
-        if (status) status.textContent = ok ? "Paired. You may close this tab." : "Pairing failed.";
-      },
-      args: [paired.ok === true],
-    });
+    await setPairingPageStatus(
+      tab.id,
+      paired.ok === true ? "Paired. You may close this tab." : "Pairing failed.",
+    );
   } catch {
-    try {
-      await chrome.scripting.executeScript({
-        target: { tabId: tab.id },
-        func: () => {
-          const status = document.getElementById("status");
-          if (status) status.textContent = "Pairing failed. Reload this page and confirm that the expected extension build is loaded.";
-        },
-      });
-    } catch {}
+    ignoreBrowserApiCall(() => setPairingPageStatus(
+      tab.id,
+      "Pairing failed. Reload this page and confirm that the expected extension build is loaded.",
+    ));
   }
 }
 
+function setPairingPageStatus(tabId, text) {
+  return chrome.scripting.executeScript({
+    target: { tabId },
+    func: (value) => {
+      const status = document.getElementById("status");
+      if (status) status.textContent = value;
+    },
+    args: [text],
+  });
+}
+
 ensureReconnectAlarm();
 void connectFromStorage();
 
@@ -162,7 +185,7 @@ function connect(endpoint, token, { reconnect = true } = {}) {
   clearTimeout(reconnectTimer);
   reconnectTimer = null;
   if (socket) {
-    try { socket.close(); } catch {}
+    closeSocketQuietly(socket);
   }
   const ws = new WebSocket(endpoint, [`mbm.${token}`]);
   socket = ws;
@@ -181,12 +204,12 @@ function connect(endpoint, token, { reconnect = true } = {}) {
     };
     ws.onopen = () => {
       if (socket !== ws) {
-        try { ws.close(); } catch {}
+        closeSocketQuietly(ws);
         settle(new Error("browser connection was superseded"));
         return;
       }
       ws.handshakeTimer = setTimeout(() => {
-        try { ws.close(1002, "browser broker handshake timed out"); } catch {}
+        closeSocketQuietly(ws, 1002, "browser broker handshake timed out");
       }, HANDSHAKE_TIMEOUT_MS);
     };
     ws.onmessage = (event) => void handleMessage(ws, event.data, () => settle());
@@ -214,12 +237,12 @@ function scheduleReconnect(endpoint, token) {
 async function handleMessage(ws, raw, onReady = () => {}) {
   let message;
   try { message = JSON.parse(String(raw)); } catch {
-    try { ws.close(1007, "invalid broker JSON"); } catch {}
+    closeSocketQuietly(ws, 1007, "invalid broker JSON");
     return;
   }
   if (message?.type === "hello") {
     if (ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
-      try { ws.close(1002, "browser broker protocol mismatch"); } catch {}
+      closeSocketQuietly(ws, 1002, "browser broker protocol mismatch");
       return;
     }
     ws.serverHelloSeen = true;
@@ -237,7 +260,7 @@ async function handleMessage(ws, raw, onReady = () => {}) {
   }
   if (message?.type === "hello_ack") {
     if (ws.bridgeReady || !ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
-      try { ws.close(1002, "invalid browser broker acknowledgement"); } catch {}
+      closeSocketQuietly(ws, 1002, "invalid browser broker acknowledgement");
       return;
     }
     clearTimeout(ws.handshakeTimer);
@@ -252,7 +275,7 @@ async function handleMessage(ws, raw, onReady = () => {}) {
     return;
   }
   if (!ws.bridgeReady) {
-    try { ws.close(1002, "browser broker acknowledgement required"); } catch {}
+    closeSocketQuietly(ws, 1002, "browser broker acknowledgement required");
     return;
   }
   if (message?.type === "cancel" && typeof message.id === "string") {
@@ -291,7 +314,7 @@ function sendResponse(ws, id, ok, result, error = "") {
   if (new TextEncoder().encode(payload).byteLength > MAX_RESULT_BYTES) {
     payload = JSON.stringify({ type: "response", id, ok: false, error: "browser result exceeds maximum size" });
   }
-  try { ws.send(payload); } catch {}
+  sendSocketQuietly(ws, payload);
 }
 
 

package/docs/ARCHITECTURE.md

@@ -109,6 +109,8 @@ All requests for a deployed Worker route to one named Durable Object. It owns:
 
 The Worker verifies OAuth, validates MCP envelopes and optional protocol headers, converts `tools/call` into WebSocket messages, correlates cancellation by access-token hash and JSON-RPC ID, and formats text/structured/image results. It has no local filesystem or process API.
 
+The current OAuth store is multi-client but not principal-aware. `client_id` identifies an MCP application/installation; it does not identify a human or service account. Every successful authorization uses the same per-workspace connection password and receives the same workspace policy ceiling. Isolated account support therefore requires explicit principals, memberships, named grants, targeted revocation, and dual Worker/local enforcement rather than treating client registrations as users. The recommended design retains one bridge-specific Durable Object and one local runtime per workspace/trust domain; see [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md).
+
 The daemon attachment deliberately omits workspace path/name/hash and process ID. Explicit authenticated tools may return workspace metadata according to local path-display policy.
 
 ### Autostart layer
@@ -138,7 +140,7 @@ flowchart LR
   CLI --> S[Autostart provider]
 ```
 
-Remote OAuth determines which client may call tools. Local stdio access relies on the local process and configuration boundary. Policy determines which tools the local daemon and relay advertise. A connector host can independently present a smaller tool subset to a session; this post-relay filtering is outside the protocol state visible to Machine Bridge. Canonical resolution limits direct filesystem tools. Processes retain local-user authority and can escape workspace constraints through their own code or system calls.
+Remote OAuth currently determines which registered client token may call tools; it does not distinguish independently authorized human principals. Local stdio access relies on the local process and configuration boundary. Policy determines which tools the local daemon and relay advertise. A connector host can independently present a smaller tool subset to a session; this post-relay filtering is outside the protocol state visible to Machine Bridge. Canonical resolution limits direct filesystem tools. Processes retain local-user authority and can escape workspace constraints through their own code or system calls.
 
 ## Remote request lifecycle
 
@@ -258,4 +260,4 @@ Third-party workflow actions are pinned to immutable commit SHAs. Dependabot pro
 - model-level prompt-injection prevention or semantic validation of browser/application actions;
 - universal desktop UI automation beyond the implemented OS Accessibility backend;
 - scripting browser-internal/enterprise-blocked pages or inaccessible cross-origin frames;
-- multi-user tenancy in one Worker deployment.
+- isolated multi-user tenancy or per-principal authorization in one Worker deployment; multiple OAuth client registrations currently share one workspace authority.

package/docs/CLIENTS.md

@@ -124,6 +124,8 @@ machine-mcp --workspace /path/to/project
 
 Enter the printed `/mcp` URL in the remote MCP connector. During OAuth authorization, verify the displayed client name and redirect URI before entering the connection password.
 
+Several OAuth clients and access tokens can coexist, but the current release does not model separate human/service principals. Every authorization that uses the shared workspace password receives the same workspace authority. Do not treat separate ChatGPT accounts as isolated Machine Bridge accounts; see [MULTI_ACCOUNT.md](MULTI_ACCOUNT.md).
+
 ## Profile guidance
 
 - `full` is the default and prioritizes immediate usability. It is a canonical contract exposing every catalog tool, shell execution, unrestricted direct filesystem paths, absolute path output, and the full parent environment. Any individual narrowing is represented as `custom`.

package/docs/ENGINEERING.md

@@ -1,6 +1,6 @@
 # Engineering principles and maintenance rules
 
-This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes. Machine-specific observations belong in the ignored `.project-local/` directory instead.
+This document records project-wide decisions that must survive individual fixes, releases, and maintainers. It is normative for repository changes together with [PROJECT_STANDARDS.md](PROJECT_STANDARDS.md). Machine-specific observations belong in the ignored `.project-local/` directory instead.
 
 ## Product and security invariants
 
@@ -146,6 +146,8 @@ Cross-platform tests must not depend on shell syntax, case-sensitive Windows pat
 - OPERATIONS contains diagnosis and recovery procedures.
 - TESTING records executable coverage and regression expectations.
 - CHANGELOG records externally relevant changes, including documentation and workflow changes.
+- PROJECT_STANDARDS defines collaboration, contract, testing, supply-chain, review, and exception policy.
+- TOOL_REFERENCE is generated from the shared MCP tool catalog and must never be maintained by hand.
 
 Documentation that claims a guarantee must identify the code or test enforcing it. Do not document an aspirational behavior as implemented.