contextcompass 2.15.4__tar.gz → 2.19.0__tar.gz

contextcompass-2.19.0/.github/workflows/python-publish.yml

@@ -0,0 +1,258 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Two paths in the git index that differ only by case are ONE file on Windows
+  # and macOS, and two on Linux. Committed from a case-sensitive machine the
+  # duplicate is invisible to everyone on Windows - their checkout silently
+  # collapses it, and whichever entry git writes last wins, so the file appears
+  # to rename itself at random.
+  #
+  # Cheap to check, miserable to diagnose: it presented as a Windows editor
+  # "corrupting" a filename for a day before the index was the obvious suspect.
+  # Runs on Linux because that is the only place both paths are visible.
+  hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: No two paths differing only by case
+        run: |
+          dupes=$(git ls-files | tr 'A-Z' 'a-z' | sort | uniq -d)
+          if [ -n "$dupes" ]; then
+            echo "Paths in the index that collide case-insensitively:"
+            echo "$dupes" | while read -r low; do
+              git ls-files | grep -ix "$low" | sed 's/^/  /'
+            done
+            echo
+            echo "On Windows these are the SAME file. Keep one:"
+            echo "  git rm --cached <the wrong one>   # index only, file stays"
+            exit 1
+          fi
+          echo "OK: no case-colliding paths"
+
+  # The tools are stdlib-only and claim >=3.10. Claiming a range without
+  # testing it is how a floor rots: the suite runs on every version the
+  # metadata promises, so the promise stays true.
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+
+      # Pinned to an exact version, unlike the actions/* pins above, because
+      # astral-sh/setup-uv does NOT publish a bare `v8` moving tag. It publishes
+      # `v3`-`v7` and then, for the 8 series, only `v8.0.0`/`v8.1.0`/`v8.2.0`.
+      # `@v8` therefore fails to resolve at all - "unable to find version v8" -
+      # which is a workflow-parse failure, not a step failure, so every matrix
+      # leg dies before it runs. `releases/latest` reporting `v8.2.0` says
+      # nothing about whether the alias exists; only the ref does.
+      # v8.2.0 declares `using: node24`, which is the point of the bump.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run the suite
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  release-build:
+    runs-on: ubuntu-latest
+    needs: [hygiene, test]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build release distributions
+        run: python -m build --sdist --wheel
+
+      # The Markdown IS the product. An implicit setuptools build produced a
+      # wheel of 28 .py files and zero .md - it succeeded, published cleanly,
+      # and shipped the tooling without the system it operates on. Nothing in a
+      # green build would have told you.
+      - name: Verify the wheel carries the payload
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+
+          whl = glob.glob("dist/*.whl")[0]
+          names = [n for n in zipfile.ZipFile(whl).namelist() if not n.endswith("/")]
+
+          # DERIVED, never hardcoded. This was written as a literal
+          # "contextcompass/_package/", and when the module was renamed to
+          # `contextcompass_cli` the check reported "payload has 0 files,
+          # expected 400+" against a wheel that was completely correct. The
+          # build was fine; the ruler was wrong, and it failed in the most
+          # alarming way it could - by claiming the product was missing.
+          # Discovering the prefix means a rename cannot stage that again.
+          prefixes = sorted({n.split("_package/")[0] + "_package/"
+                             for n in names if "/_package/" in n})
+
+          problems = []
+          if len(prefixes) != 1:
+              problems.append(
+                  f"expected exactly one _package/ root in the wheel, found {prefixes}")
+          prefix = prefixes[0] if prefixes else "<none>/_package/"
+
+          payload = [n for n in names if n.startswith(prefix)]
+          markdown = [n for n in payload if n.lower().endswith(".md")]
+
+          print(f"wheel    : {whl}")
+          print(f"files    : {len(names)}")
+          print(f"payload  : {prefix}  ({len(payload)} files)")
+          print(f"markdown : {len(markdown)}")
+
+          if len(payload) < 400:
+              problems.append(f"payload has {len(payload)} files, expected 400+")
+          if len(markdown) < 300:
+              problems.append(f"only {len(markdown)} markdown files in the payload")
+          for required in ("AGENTS.MD", "SKILLS.MD", "MANIFEST.md"):
+              if prefix + required not in names:
+                  problems.append(f"missing {prefix}{required}")
+          if not any(n.endswith("entry_points.txt") for n in names):
+              problems.append("no console script entry point")
+
+          if problems:
+              print("\nFAILED:")
+              for p in problems:
+                  print(f"  - {p}")
+              sys.exit(1)
+          print("\nOK: wheel carries the full package")
+          PY
+
+      # The version lives in one place and the manifest records it separately.
+      # A tag that disagrees with either is a release nobody can reason about.
+      - name: Verify version agreement
+        if: github.event_name == 'release'
+        run: |
+          python - <<'PY'
+          import glob, os, re, sys, zipfile
+
+          whl = glob.glob("dist/*.whl")[0]
+          wheel_version = re.search(r"-(\d+\.\d+\.\d+)-", whl).group(1)
+          zf = zipfile.ZipFile(whl)
+          # Derived for the same reason as the payload check above.
+          manifest_name = next(n for n in zf.namelist()
+                               if n.endswith("_package/MANIFEST.md"))
+          manifest = zf.read(manifest_name).decode()
+          manifest_version = next(
+              l.split("|")[2].strip() for l in manifest.splitlines()
+              if l.startswith("| package_version |"))
+          tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
+
+          print(f"tag {tag}  wheel {wheel_version}  manifest {manifest_version}")
+          if not (tag == wheel_version == manifest_version):
+              sys.exit("FAILED: tag, wheel and manifest versions disagree")
+          print("OK")
+          PY
+
+      - name: Install the wheel and exercise the CLI
+        run: |
+          python -m venv /tmp/probe
+          /tmp/probe/bin/pip install --quiet dist/*.whl
+          mkdir -p /tmp/target && cd /tmp/target
+          /tmp/probe/bin/contextcompass version
+          /tmp/probe/bin/contextcompass init
+          /tmp/probe/bin/python context_compass/tools/package_manifest.py \
+              --root context_compass --check
+
+      # v4 is node20 and would draw the same deprecation notice as the pins
+      # above. It escaped the last run's warnings only because the wheel check
+      # failed first, so this step never executed - an absence of warning that
+      # meant "never reached", not "fine".
+      #
+      # upload and download move together and stay on the same major: the
+      # artifact each side speaks is versioned, and a mismatched pair fails at
+      # download, in the publish job, after everything else has gone green.
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write
+    environment:
+      # Must match the "Environment name" on the PyPI trusted publisher exactly.
+      # PyPI's OIDC check compares repository + workflow filename + environment;
+      # a mismatch fails auth at publish time, after a green build.
+      name: prod
+      url: https://pypi.org/project/contextcompass/
+
+    steps:
+      # Same major as the upload above. Do not bump one without the other.
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: release-dists
+          path: dist/
+
+      # TWO WAYS TO AUTHENTICATE, AND YOU ONLY NEED ONE.
+      #
+      # Trusted publishing (OIDC) is the one configured on PyPI: it matches
+      # repository + workflow filename + environment and needs NO secret at all.
+      # That is why `id-token: write` and `environment.name: prod` above are the
+      # real credentials here - a token adds nothing when OIDC is working, and a
+      # long-lived token that leaks is worse than one that never existed.
+      #
+      # The token path stays as a fallback for the case where the pending
+      # publisher has not been approved yet, or you are publishing from a fork
+      # where OIDC will not match. A REPOSITORY secret is fine: repo secrets are
+      # visible to jobs that declare an environment, and an environment secret of
+      # the same name would simply take precedence.
+      #
+      # `secrets` cannot be read in a job-level `if`, so presence is resolved
+      # into a step output first. Without that indirection the two publish steps
+      # cannot be made mutually exclusive.
+      - name: Decide how to authenticate
+        id: auth
+        env:
+          TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "method=token" >> "$GITHUB_OUTPUT"
+            echo "Using the PYPI_TOKEN repository secret."
+            echo "NOTE: trusted publishing needs no secret. Once the pending"
+            echo "      publisher on PyPI is approved, delete PYPI_TOKEN and this"
+            echo "      workflow switches to OIDC on its own."
+          else
+            echo "method=oidc" >> "$GITHUB_OUTPUT"
+            echo "Using trusted publishing (OIDC). No secret required."
+          fi
+
+      - name: Publish to PyPI (trusted publishing)
+        if: steps.auth.outputs.method == 'oidc'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Publish to PyPI (API token)
+        if: steps.auth.outputs.method == 'token'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+          packages-dir: dist/

{contextcompass-2.15.4 → contextcompass-2.19.0}/.gitignore

@@ -21,6 +21,10 @@ htmlcov/
 .idea/
 .vscode/
 
+# Local operating state and machine-specific harness settings
+/.local/
+/src/.codex/
+
 # OS
 .DS_Store
 Thumbs.db

contextcompass-2.19.0/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+This repository is Context Compass itself. Which guidance applies depends on
+why the agent is here.
+
+- Maintaining this repository (changing the payload, tools, tests, packaging,
+  or these guides): read [contributor/AGENTS.md](contributor/AGENTS.md) next
+  and follow that route.
+- Using Context Compass in another project: start with
+  [the Quickstart](README.md#quickstart). After installing, the agent follows
+  `context_compass/AGENTS.MD` inside that project (`src/context_compass/`
+  here is this repository's clean product source, not an installed copy).
+
+Keep detailed repository-maintenance agent instructions in `contributor/`;
+keep this root file as the entrypoint.

{contextcompass-2.15.4 → contextcompass-2.19.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: contextcompass
-Version: 2.15.4
+Version: 2.19.0
 Summary: Durable, file-backed execution state for coding agents.
-Project-URL: Homepage, https://github.com/Synaptic724/contextcompass
-Project-URL: Repository, https://github.com/Synaptic724/contextcompass
+Project-URL: Homepage, https://github.com/Synaptic724/context_compass
+Project-URL: Repository, https://github.com/Synaptic724/context_compass
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -24,6 +24,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/contextcompass.svg)](https://pypi.org/project/contextcompass/)
 [![Python](https://img.shields.io/pypi/pyversions/contextcompass.svg)](https://pypi.org/project/contextcompass/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/Synaptic724/context_compass?style=social)](https://github.com/Synaptic724/context_compass/stargazers)
 
 **Working memory for coding agents, stored in your repo instead of a chat window.**
 
@@ -37,6 +38,8 @@ That writes a `context_compass/` directory into your project. Point an agent at
 live in files you own — surviving compaction, new chats, model swaps, and the next
 agent.
 
+> **⭐ If this is useful, please star the repo — it's how people find it.**
+
 ## Why It Exists
 
 Agent work falls apart the second the chat stops being fresh. The context gets
@@ -78,10 +81,11 @@ uvx contextcompass init
 Nothing lands in your project's dependency tree, because a repo-scaffolding tool
 has no business there.
 
-Pin a version for reproducibility, or track the latest:
+Pin a published version for reproducibility, or track the latest. Replace
+`X.Y.Z` with the release you want:
 
 ```bash
-uvx contextcompass@2.15.4 init     # exact, repeatable
+uvx contextcompass@X.Y.Z init      # exact, published release
 uvx contextcompass@latest init     # whatever is newest
 ```
 
@@ -120,14 +124,14 @@ pip install --user contextcompass && contextcompass init
 The package is **Markdown**. If all you want is the system, copy the folder:
 
 ```bash
-git clone https://github.com/Synaptic724/contextcompass
-cp -r contextcompass/src/context_compass my-repo/
+git clone https://github.com/Synaptic724/context_compass
+cp -r context_compass/src/context_compass my-repo/
 ```
 
 ```powershell
 # Windows
-git clone https://github.com/Synaptic724/contextcompass
-Copy-Item -Recurse contextcompass\src\context_compass my-repo\
+git clone https://github.com/Synaptic724/context_compass
+Copy-Item -Recurse context_compass\src\context_compass my-repo\
 ```
 
 Clone when you want to read the source first, work offline, vendor a specific
@@ -140,8 +144,8 @@ source graph, and upgrade an install. **Python 3.10+, stdlib only, no dependenci
 ever.** An agent that has to `pip install` before it can read a document is an
 agent that cannot read the document on a fresh clone.
 
-Tested on 3.10 through 3.14 (including free-threaded 3.14t) on Linux and Windows,
-on every push. Verify an install any time:
+The release workflow runs the suite on Python 3.10 through 3.14 on Linux and
+Windows. Verify an install any time:
 
 ```bash
 python context_compass/tools/package_manifest.py --root context_compass --check
@@ -151,14 +155,97 @@ python context_compass/tools/package_manifest.py --root context_compass --check
 
 1. Point your agent at `context_compass/AGENTS.MD` and ask it to onboard as an
    `engineer`.
-2. Approve the certification step it asks for: `CERTIFY: APPROVED`.
+2. Under the default onboarding flow, approve the certification step it asks
+   for: `CERTIFY: APPROVED`.
 3. Work normally. The agent routes through `attention_board.md` and the active
    ticket, and writes findings into ticket `## Notes`.
 4. Commit `context_compass/`. It is your repository's memory now, and it is meant
    to be reviewed and diffed like any other source.
-5. **After every compaction or handoff, tell the next agent to re-onboard.** That
-   is the whole trick — it rebuilds context from the repo instead of guessing from
-   a half-remembered chat.
+5. **After every compaction or handoff, the agent must re-onboard.** Add the
+   recovery reminder to your tool's custom instructions as described below. If
+   you skip that setup, remind the agent yourself.
+
+### Set up recovery once
+
+During onboarding, the agent checks whether your personal custom instructions
+already include Context Compass. If they do, it keeps your existing setup. If
+they do not, it offers a short setup form for Codex, Claude Code, or Gemini CLI.
+
+You choose whether Context Compass should own all tickets, plans, and working
+notes; whether agents can coordinate; when subagents may be created; and whether
+those subagents should complete their own onboarding. The agent shows the exact
+addition and asks before editing your personal instructions. You can also add
+the text yourself or skip setup. Existing preferences stay in place.
+
+The reminder sends the agent back to the repo's onboarding and recovery rules
+after compaction. It lives in your tool's personal configuration, while your
+project's work stays in Context Compass. Package installs and upgrades do not
+edit those personal files automatically.
+
+### Project-specific onboarding
+
+If your project needs a different onboarding routine, put explicit instructions
+in `context_compass/special_instructions/`. Agents read that folder before
+applying onboarding or re-onboarding defaults, so you do not need to fork the
+package's `AGENTS.MD` to change a particular requirement.
+
+State which requirement changes, where the override applies, and what should
+happen instead. Everything you do not override remains in force. Later role or
+skill documents do not undo the override, and agents reload it after compaction.
+Conflicting project instructions need clarification rather than a filename-based
+winner. The shipped folder contains no active override; normal onboarding is
+unchanged until you add one.
+
+These are project-policy overrides, not changes to the agent platform's system
+instructions or tool permissions.
+
+### Know Who Is Doing The Work
+
+Agents represent themselves by their assigned name and actual role, including
+in their replies, ticket posts and Notes. If several agents share one GitHub
+account, you can still tell who wrote the finding or did the work. The person
+accountable for a ticket, its executor, its authors, its publisher and its
+reviewer are recorded separately. Posting a result is not the same as authoring
+it, and reviewing your own work is not independent review.
+
+### Choose Your Ticket Design
+
+The full Epic, Story and Task templates remain available. For new tickets, you
+can point Context Compass at your own complete templates in
+`context_compass/config/context_compass_config.yaml`:
+
+```yaml
+ticket_design:
+  instructions: >
+    Use our complete ticket templates and record the actual author of each Note.
+    Include Agile metadata only when the selected ticket design calls for it.
+  templates:
+    epic: templates/epic_template.md
+    story: templates/story_template.md
+    task: user_defined/ticket_templates/my_task.md
+```
+
+Paths are relative to `context_compass/`. Put your custom file at the configured
+path and retain the complete ticket sections, evidence and acceptance gates.
+This setting does not select an agent role or rewrite tickets you already have.
+
+An Agile design can include optional versioned metadata describing the current
+phase, execution condition and resolution. That lets you distinguish work in
+review from work waiting on a blocker, without treating GitHub's open/closed
+flag as the whole story. Notes remain in the ticket body, and acceptance still
+needs the actual acceptance and validation evidence.
+
+The canonical definition is `context_compass/templates/ticket_contract.json`.
+The included helper can check a completed new-format ticket or build a hashed
+contract bundle for a cloud reader, without posting anything to GitHub:
+
+```bash
+python context_compass/tools/ticket_design.py validate --kind task --ticket path/to/task.md
+python context_compass/tools/ticket_design.py bundle --kind task --backend local --out ticket_contract.md
+```
+
+Bundle output refuses to replace an existing file. Custom templates can contain
+project-private information, so review a generated bundle before sharing it.
 
 ## Core Features
 
@@ -172,7 +259,7 @@ may touch anything.
 
 ### 2) Certification gate
 
-Nothing executes on trust. Before tools or edits, the agent posts what it read and
+Under the default onboarding rules, before tools or edits the agent posts what it read and
 what each document changes about its behavior, then waits for a message containing
 `AGENT_NAME: <name>` and the exact token `CERTIFY: APPROVED`. Proof is a
 comprehension claim, not a tool log — "I ran `cat`" is not evidence of reading.
@@ -241,6 +328,10 @@ Not every handoff should be broadcast. `mailbox_board.md` carries point-to-point
 messages between named agents — handoff, notice, question, ack — so directed
 communication does not turn the routing board into noise.
 
+If your agents have Codex MCP messaging tools, you can use those for handoffs
+instead. The switch changes how messages travel, not where your work is kept.
+Registration, counters, tickets and the boards keep their existing jobs.
+
 ## Roles
 
 `SKILLS.MD` is the **single role registry**. A role exists if and only if it has a
@@ -289,13 +380,15 @@ a folder on disk with no row is scaffolding, not a selectable role.
 
 ## How A Session Actually Runs
 
-**Onboard.** The agent reads `AGENTS.MD`, then the execution contract, the config,
-and `SKILLS.MD`. It lists the roles and asks which to take. It walks the chain
+**Onboard.** The agent starts with `AGENTS.MD` and reads `special_instructions/`
+before applying onboarding defaults. It then follows the effective requirements
+for the execution contract, config, and `SKILLS.MD`. Normally it lists the roles
+and asks which to take. It walks the chain
 parent-first and reads every baseline section — for `engineer` that is its own
 required skills, the parent's active skills, and the system-orientation set
 (`src_architecture.md` plus the architecture and component indexes).
 
-**Certify.** It posts what it read and what each document changes about its
+**Certify (default).** It posts what it read and what each document changes about its
 behavior. You reply with `AGENT_NAME: helper_1` and `CERTIFY: APPROVED`.
 
 **Route.** It opens `attention_board.md` and picks up the active row:
@@ -328,7 +421,7 @@ that ticket, reads the notes, and continues — from evidence, not from memory.
 
 ## The Boards
 
-Three files, each with one job. All three carry `USER-DEFINED` regions that no
+Three default boards, each with one job. All carry `USER-DEFINED` regions that no
 tool writes to in any mode, so your rows survive upgrades while the surrounding
 structure improves.
 
@@ -342,6 +435,9 @@ for analysis, not for artifact paths. Durable history belongs in ticket notes.
 **`mailbox_board.md`** — point-to-point messages plus a checked-in roster, so
 concurrent agents can see who is live and hand work to a named recipient.
 
+**`issue_board.md`** — optional GitHub-mode responsibility map. It records which
+Context Compass agent owns or reviews each Issue without copying Issue content.
+
 ## Repository Anatomy
 
 ```
@@ -351,6 +447,7 @@ context_compass/
   CONTEXT_COMPACTION.md         compaction and handoff contract
   config/                       behaviour settings (never a role list)
   attention_board.md            routing
+  issue_board.md                optional GitHub-mode agent claims
   artifact_board.md             artifact lifecycle
   mailbox_board.md              agent-to-agent messages
   agent_onboarding/
@@ -385,6 +482,8 @@ alone. Notable keys:
 | key | effect |
 | --- | --- |
 | `system_of_record.enforce` | when `true`, agents may not use harness task lists, plans or session memory to track work. This package is the only tracking surface. |
+| `work_tracking.backend` | `local` reads ticket folders; `github_codex_plugin` uses the connected GitHub plugin's Issues |
+| `agent_communication.backend` | `mailbox` sends file messages; `codex_mcp` uses available chat tools while keeping board/session state local |
 | `workflow.ticket_microcycle.*` | strict or relaxed loop, note score floor, expansion gate |
 | `workflow.note_behavior.*` | append-only notes, required evidence ranges, per-ticket focus |
 | `artifacts.*` | store root, disposition defaults, ticket-link requirements |
@@ -393,6 +492,65 @@ alone. Notable keys:
 Config is merged key by key on upgrade. New keys arrive with their comments; a
 value you set is never reset.
 
+### Optional GitHub Mode
+
+Choose where your agent reads and updates tickets in YAML:
+
+```yaml
+work_tracking:
+  backend: local
+```
+
+`local` is the default and uses the existing epic, story, and task folders. To
+use Issues through the connected GitHub plugin, choose:
+
+```yaml
+work_tracking:
+  backend: github_codex_plugin
+  github_codex_plugin:
+    connection_nickname: "Work account"
+    issues_repository: YOUR_OWNER/YOUR_REPO
+    project_url: "" # optional
+```
+
+Connect the GitHub plugin with access to that repository. Each Issue keeps the
+matching Epic/Story/Task template, including Status and Notes in its body.
+Agents read the selected backend's skills during onboarding and recovery.
+Agent claims, active focus, mailbox, artifacts, special instructions, and system
+docs stay in your repo. This mode uses plugin authentication and does not require
+CLI setup or a token in YAML.
+
+Give your connected GitHub account a nickname in Codex, such as `Work account`,
+and copy that exact nickname into YAML. It tells the agent which connection to
+use, independently of the target repository owner. The agent verifies the
+selected profile and stops if the nickname is missing or ambiguous; it does
+not fall back to another account. Connection IDs and credentials stay out of
+the config. Existing plugin configs must add this setting explicitly.
+
+The YAML choices, plugin capabilities, and existing-config migration are in
+[the GitHub setup guide](src/context_compass/agent_onboarding/default/general/skills/github/README.md).
+Existing file tickets are not published or migrated just because you enable the
+mode; review their content and destination first.
+
+### Optional MCP Messaging
+
+For agents with Codex MCP chat tools, choose:
+
+```yaml
+agent_communication:
+  backend: codex_mcp
+```
+
+`mailbox` remains the default, including older installs without this setting.
+Either choice works with local tickets or GitHub Issues. MCP agents read the
+MCP messaging skill instead of mailbox messaging instructions and use the chat
+tools for authorized handoffs and replies. The setting does not install an MCP
+server or grant permission to contact agents.
+
+The existing mailbox board still holds registration and setup outcomes.
+MCP agents read just those state sections, not stored messages or
+message alerts. Existing messages and all other boards stay intact.
+
 ## Upgrading An Existing Install
 
 ```bash
@@ -484,16 +642,14 @@ tooling is built around not destroying that work.
   refuses without a terminal to ask at.
 - **Line-range indexes carry staleness proofs**, and every consumer refuses on
   mismatch rather than returning confidently wrong content.
-- **419 tests, plus mutation testing.** A green suite is equally consistent with
+- **Regression tests, plus mutation testing.** A green suite is equally consistent with
   "the code is correct" and "the tests assert nothing", so
   `tests/mutation_check.py` applies 49 deliberate defects and requires at least
   one test to fail for each. Several survived their first run; each named a real
   gap.
 
-```bash
-uv sync && uv run pytest                 # the suite
-uv run python tests/mutation_check.py    # prove the suite has teeth
-```
+Local setup, test commands, and mutation checks are covered in the
+[contributor testing guide](contributor/testing.md).
 
 ### The source graph is honest about what it cannot know
 
@@ -548,6 +704,12 @@ If you want project memory that stays with the repo, survives branch work, handl
 handoffs, resists drift, and still makes sense when another agent shows up later —
 that is exactly what this system is for.
 
+## Contributing
+
+If you are changing Context Compass itself, start with the
+[contributor guide](contributor/README.md). It covers repository maintenance,
+preserving user content, testing, generated files, version bumps, and releases.
+
 ## License and Trademarks
 
 The software is licensed under **Apache License 2.0** — see [LICENSE](LICENSE).