test(sync): quarantine circular-relations test in CI pending #940

The batch-indexing race has now flaked three CI rounds today. Skipped under CI only (still runs locally); #940 tracks the root cause. Signed-off-by: phernandez <paul@basicmachines.co>
fix(ci): anchor paged-status test fake on the &page separator
2026-06-21 13:47:35 +00:00 · 2026-06-10 12:10:01 -05:00 · 2026-06-10 11:12:53 -05:00 · 2026-06-10 10:35:55 -05:00 · 2026-06-10 09:44:36 -05:00 · 2026-06-10 09:43:47 -05:00
63 changed files with 6305 additions and 261 deletions
@@ -0,0 +1,68 @@
+---
+name: code-review
+description: Use when reviewing Basic Machines code for house style, architecture risk, pre-merge hardening, or whether a change fits basic-memory/basic-memory-cloud conventions.
+license: MIT
+---
+
+# Basic Machines Review
+
+Use this skill for repo-local review passes where ordinary code review needs Basic Machines
+house style and architecture judgment. Report findings only; do not edit code unless the user
+asks you to fix specific findings.
+
+## Scope
+
+Review the current diff or named files against:
+
+- The repo's `AGENTS.md` / `CLAUDE.md`
+- `docs/ENGINEERING_STYLE.md`
+- The touched code paths and tests
+
+Apply only the guidance for the active repo. In `basic-memory`, prioritize local-first
+file/database/MCP boundaries. In `basic-memory-cloud`, prioritize tenant/workspace isolation,
+cloud worker behavior, and web-v2 state/runtime boundaries.
+
+## Review Rubric
+
+Report only concrete, falsifiable risks:
+
+- **Cognitive load:** Is the change harder to understand than the problem requires?
+- **Change propagation:** Will one product change force edits across unrelated layers?
+- **Knowledge duplication:** Is the same rule encoded in multiple places that can drift?
+- **Accidental complexity:** Did the change add abstractions, fallbacks, or state without need?
+- **Dependency direction:** Are API/MCP/CLI, services, repositories, and UI stores respecting
+  their intended boundaries?
+- **Domain model distortion:** Do names and types still match the product concept, or did a
+  transport/storage detail leak into the domain?
+- **Test oracle quality:** Would the tests fail for the bug or regression the change claims to
+  protect against?
+
+## House Rules To Check Explicitly
+
+- No speculative `getattr(obj, "attr", default)` for unknown model shapes.
+- No broad exception swallowing, warning-only failure paths, or hidden fallback behavior.
+- No casts or `Any` that hide an unclear type relationship.
+- Dataclasses for internal value/result objects; Pydantic at validation/serialization
+  boundaries.
+- Narrow `Protocol`s when only a capability is needed.
+- Explicit async/resource ownership, cancellation, and cleanup.
+- Meaningful regression tests or verification for risky changes.
+- Comments explain why, not what.
+
+## Reporting Format
+
+Lead with findings ordered by severity. Each finding should include:
+
+| Severity | Use for |
+| -------- | ------- |
+| `high` | A likely correctness, security, data-loss, or tenant/workspace isolation failure |
+| `medium` | A concrete maintainability or boundary risk that can cause future defects |
+| `low` | A minor consistency issue, ambiguous guidance, or review-only cleanup |
+
+```text
+severity | file:line | risk category | claim
+Why: concrete behavior or code path that proves the risk.
+Fix: smallest practical change, or "none obvious" if the risk needs product input.
+```
+
+If there are no findings, say so and note any verification gaps that remain.
@@ -0,0 +1,48 @@
+---
+name: fix-pr-issues
+description: Use when addressing Basic Memory pull request feedback, failed checks, or BM Bossbot blockers from Codex.
+---
+
+# Fix Basic Memory PR Issues
+
+Resolve PR feedback and failed checks, then wait for BM Bossbot to approve the
+new head SHA. This skill never merges a PR.
+
+## Gather
+
+1. Identify the PR:
+   - `gh pr view --json number,url,headRefOid,mergeStateStatus,statusCheckRollup`
+
+2. Collect feedback:
+   - PR comments and review summaries
+   - inline review comments and unresolved review threads
+   - failed GitHub Actions jobs and relevant logs
+   - the managed `BM_BOSSBOT_SUMMARY` block in the PR body
+
+3. Build a short issue ledger:
+   - source
+   - concrete problem
+   - expected fix
+   - verification needed
+
+## Fix
+
+1. Address one ledger item at a time.
+2. Read each file in full before editing it.
+3. Keep diffs narrow and preserve unrelated user changes.
+4. Run the smallest meaningful verification first, then widen as needed.
+5. Commit with `git commit -s` when code or docs changed.
+
+## Push And Recheck
+
+1. Push the branch.
+2. Watch checks for the new `headRefOid`.
+3. Wait for the required `BM Bossbot Approval` status to pass on that exact SHA.
+4. If BM Bossbot reviews an older SHA, treat the approval as stale and keep
+   waiting for the current one.
+
+## Reply
+
+For each addressed comment or blocker, reply with the fix commit, verification
+run, and current BM Bossbot status. Do not resolve or dismiss substantive
+feedback without evidence.
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Fix PR Issues"
+  short_description: "Address PR feedback and BM Bossbot blockers"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#2563EB"
+  default_prompt: "Use $fix-pr-issues to address PR feedback and wait for BM Bossbot Approval on the latest head SHA."
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 24 24" fill="none" stroke="#111827" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M3 12h4l2-6 4 12 2-6h6"/>
+  <path d="M4 20h16"/>
+</svg>
+
@@ -0,0 +1,247 @@
+---
+name: infographics
+description: Use when generating Basic Memory PR, changelog, release, or weekly images from Codex.
+---
+
+# Basic Memory Images
+
+Generate repository visuals with evidence-grounded content and canonical output
+paths. The file and marker names still say "infographic" for compatibility, but
+PR generation is image-first: scene, poster, painting, photograph, cover,
+tableau, staged artifact, or another editorial visual moment that describes the
+intent of the PR. PR images are non-gating BM Bossbot artifacts; changelog and
+release-summary images are manual evidence-pack workflows.
+
+## Output Contract
+
+- Base output directory: `docs/assets/infographics/`
+- PR image: `docs/assets/infographics/pr-<number>.webp`
+- Changelog image: `docs/assets/infographics/changelog.webp`
+- Weekly image:
+  - This is always a 2-Week Retro window: previous ISO week through current ISO
+    week (`start-week = current-week - 1`, `end-week = current-week`).
+  - Same year window: `docs/assets/infographics/<year>-w<start-week>-w<end-week>.webp`
+  - Cross-year window:
+    `docs/assets/infographics/<start-year>-w<start-week>-<end-year>-w<end-week>.webp`
+
+## PR Mode
+
+PR mode uses the BM Bossbot summary block as source material. Do not hand-write
+claims that are not present in the PR body.
+
+1. Fetch the PR body:
+
+```bash
+gh pr view <number> --json body --jq '.body // ""' > /tmp/bm-pr-body.md
+```
+
+2. Generate the canonical asset:
+
+```bash
+uv run --script scripts/generate_pr_infographic.py \
+  --pr-number <number> \
+  --pr-body-file /tmp/bm-pr-body.md \
+  --theme "<optional visual theme>" \
+  --provenance-output /tmp/bm-infographic-provenance.md \
+  --output docs/assets/infographics/pr-<number>.webp
+```
+
+If the PR body contains a managed image theme block, the script reads it
+automatically:
+
+```markdown
+<!-- BM_INFOGRAPHIC_THEME:start -->
+<theme>
+<!-- BM_INFOGRAPHIC_THEME:end -->
+```
+
+Before spending an image call, test the prompt path locally:
+
+```bash
+uv run --script scripts/generate_pr_infographic.py \
+  --pr-number <number> \
+  --pr-body-file /tmp/bm-pr-body.md \
+  --theme "<optional visual theme>" \
+  --output docs/assets/infographics/pr-<number>.webp \
+  --print-prompt
+```
+
+`--dry-run` is an alias for `--print-prompt`; both print the final prompt and
+exit without calling OpenAI.
+
+When no theme is supplied, the script selects a deterministic BM visual
+direction from the style pool below based on the PR number and Bossbot summary.
+This keeps repeated PR images from collapsing into the same generic visual.
+
+When the image is generated, also write provenance with
+`--provenance-output <path>`. BM Bossbot publishes that managed block into the
+PR body with these markers:
+
+```markdown
+<!-- BM_INFOGRAPHIC_PROVENANCE:start -->
+...
+<!-- BM_INFOGRAPHIC_PROVENANCE:end -->
+```
+
+The provenance block records the generated asset path, image model, size,
+quality, image mode, theme source, and selected visual direction. It
+intentionally does not dump the full generated prompt into the PR body. Treat
+this block as debugging and creative provenance only; it is not a merge gate.
+
+The PR image is visual support only. The authoritative merge gate is the
+GitHub commit status named `BM Bossbot Approval`.
+
+## Changelog Mode
+
+Build an evidence pack before writing a prompt:
+
+- diff truth source: merged PR diffs, merge commits, or local reconstructed diffs
+- changed-file orientation: `git diff --stat` plus key file reads
+- impact ledger: before/after outcomes tied to actual changes
+- discard list: misleading titles, reverted work, rename-only churn, speculative TODOs
+- chosen image form: poster, scene, tableau, cover, painting, photograph,
+  staged artifact, or another editorial visual moment
+- chosen BM style category: exactly one category from the selection pool below
+
+Read these references before drafting the prompt:
+
+- `references/prompt-blueprint.md`
+- `references/style-balance.md`
+
+Read the current `CHANGELOG.md` entries and include the latest meaningful
+changes.
+
+## Style And Category Selection
+
+Select exactly one BM style category per image based on semantic fit. The
+visual language should be recognizable and tasteful, while staying
+business-readable.
+
+Create an image-first visual form that communicates the change: poster, scene,
+tableau, cover image, painting, photograph, staged artifact, or another
+editorial visual moment. Maps, diagrams, dossiers, charts, and labels can appear
+as props inside the scene, but do not make a text-heavy infographic.
+
+BM category pool:
+
+- computer science college textbooks: SICP-style diagrams, algorithms lectures,
+  compiler pipelines, automata, database systems, type theory, operating systems
+- classic literature subjects: sea voyages, gothic manors, Dickensian city maps,
+  Austen social graphs, library marginalia, travel journals
+- fantasy/D&D-inspired: quest maps, dungeon keys, guild ledgers, spellbooks,
+  bestiaries, tavern notice boards; no copyrighted settings
+- Music: Metal, Hard Rock, Punk, techno, soul, reggae bands; no pop music, no
+  direct band logos, album covers, or musician likenesses
+- sci-fi: Star Wars inspired knockoff, Spaceballs-adjacent space opera, fleet
+  routes, mission consoles, contraband manifests; avoid copyrighted characters,
+  logos, or named fictional universes
+- Conan the barbarian-inspired sword-and-sorcery: ruined temples, desert routes,
+  battle standards, ancient maps; no named character likenesses
+- Comic books: issue covers, splash pages, action-panel maps, caption boxes,
+  halftone energy, clean sound-effect typography
+- French new wave movies: poster style, stark typography, city route maps,
+  jump-cut sequencing, high-contrast editorial photography cues
+- WWII propaganda posters: home-front public-information poster language,
+  logistics arrows, ration charts, mobilization maps, bold simplified figures;
+  no real-world party symbols, hate imagery, dehumanizing slogans, or false
+  historical claims
+- Italian movie posters: hand-painted drama, bold credits, expressive color,
+  route-map collage, 1960s or 1970s cinema energy; no direct film titles or
+  actor likenesses
+- Shakespeare: stage maps, acts and scenes, dramatis personae, royal courts,
+  backstage cue sheets
+- Greek mythology: temple diagrams, constellation routes, hero's journey maps,
+  oracle tablets, labyrinths, ship routes
+- noir detective boards: case files, red-string maps, typed evidence labels,
+  precinct wall charts
+- NASA mission-control dashboards: launch timelines, telemetry maps, orbital
+  routes, status boards
+- space exploration and astronomy: celestial atlases, observatory charts,
+  star-field maps, orbital mechanics diagrams, planetary survey routes,
+  telescope annotations, mission trajectories, deep-space timelines
+- paintings: abstract painting, classical landscape, Remington-inspired western
+  action painting, Rembrandt-inspired chiaroscuro, historical mural, stormy
+  seascape, allegorical editorial painting
+- classic black-and-white photography: documentary field report, newsroom
+  archive print, editorial photo essay, street photography, high-contrast
+  darkroom print, contact sheet, civic infrastructure photograph
+- 80's action movies: practical explosions, smoky backlit warehouses, neon city
+  streets, helicopter searchlights, mission dossiers, heroic silhouettes,
+  high-stakes countdowns, painted ensemble posters; no direct actor likenesses,
+  real film titles, franchise marks, or catchphrases
+- alchemy manuscripts: transformation diagrams, annotated symbols, recipe-like
+  process maps, illuminated margins
+- brutalist civic planning: transit maps, concrete signage, zoning blocks,
+  infrastructure diagrams
+
+Selection rules:
+
+- Pick one category only; do not create mixed mashups.
+- Pick the most appropriate image form. Prefer an actual scene, poster,
+  painting, photograph, tableau, or cover over a text-heavy infographic.
+- Match metaphor to content, but do not overthink it. The category is a creative
+  catalyst, not a semantic constraint.
+- Use a polished editorial rendering direction: smooth anti-aliased
+  text, high contrast, clean edges, readable labels.
+- Make the category drive the composition through a readable staged moment,
+  editorial composition, symbolic environment, route, artifact, or visual
+  metaphor.
+- Keep the structure literal enough to aid understanding, but not so heavy that
+  it obscures engineering meaning.
+- Give the image generator creative latitude on layout, structure, color palette,
+  and visual metaphors. Be precise about what content to show, loose about how
+  to show it.
+- Do not use copyrighted characters, logos, or named fictional universes. Use
+  genre cues, knockoffs, and original compositions instead.
+
+## Content-First Aesthetic Contract
+
+The meaning must be readable and clearly hierarchical. Everything else is
+creative territory: image form, layout, visual metaphors, decorative elements,
+color choices, and category-specific visual language.
+
+Hierarchy:
+
+1. Meaning: what shipped, what changed, and why it matters must be clear.
+2. If the image uses text, labels, sections, or evidence bullets, they must be
+   legible.
+3. The selected category's visual DNA should drive the composition as a poster,
+   scene, painting, photograph, tableau, cover, or symbolic object arrangement.
+4. Do not play it safe. A visually striking image that someone wants to look at
+   beats a correct but boring one.
+
+Hard rules:
+
+- Content sections and labels must be readable when present. Text cannot be
+  obscured by decorations.
+- Do not use lore-heavy copy that competes with engineering or business meaning.
+- Every prompt must include a clear image-first composition cue: a staged scene,
+  poster composition, painting, photograph, symbolic tableau, hero object,
+  mission room, dossier, artifact, route, or visual metaphor.
+- Do not over-prescribe exact coordinates or panel geometry; give a composition
+  backbone and let the model compose around it.
+
+## Generation
+
+1. Write the final prompt to a temporary markdown file.
+2. Generate with the shared image helper:
+
+```bash
+uv run --script scripts/generate_infographic.py \
+  --prompt-file /tmp/bm-infographic-prompt.md \
+  --output docs/assets/infographics/<name>.webp
+```
+
+3. Verify the image exists and is readable before reporting success.
+
+## Quality Bar
+
+- Tell a concrete before/after value story, not vague improvement claims.
+- Stay understandable for both engineers and non-technical stakeholders.
+- Use plain-language section titles and labels when text is present.
+- Include clear visual hierarchy: title, staged focal point, symbolic scene,
+  evidence props, or hero object.
+- Avoid invented facts; only use provided source material.
+- Favor shipped outcomes over intermediate or reverted work.
+- Preserve readability with high contrast, non-tiny labels, and uncluttered
+  layout.
@@ -0,0 +1,7 @@
+interface:
+  display_name: "Infographics"
+  short_description: "Generate Basic Memory repo infographics"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#2563EB"
+  default_prompt: "Use $infographics to generate a Basic Memory PR or changelog infographic with canonical output paths."
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 24 24" fill="none" stroke="#111827" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M3 12h4l2-6 4 12 2-6h6"/>
+  <path d="M4 20h16"/>
+</svg>
+
@@ -0,0 +1,72 @@
+# Prompt Blueprint
+
+Convert an evidence pack into a final visual prompt. Be precise about the
+content and loose about visual execution.
+
+## Required Inputs
+
+- Diff truth source summary
+- Changed-file orientation summary
+- Impact ledger with before/after outcomes
+- Discard list for excluded noise
+- Chosen image form
+- Chosen BM style category
+
+## Prompt Shape
+
+```text
+Create a polished Basic Memory editorial image inspired by
+<BM_STYLE_CATEGORY>. Use a poster, scene, tableau, painting, photograph, cover
+image, staged artifact, or another image-first form that best communicates the
+intent. Use HD editorial rendering with smooth anti-aliased text when text is
+present. Go bold and let the selected category drive the visual language through
+original, non-infringing cues.
+
+TITLE:
+- "<clear title>"
+- "<scope subtitle>"
+
+COMPOSITION:
+- Recreate a clear staged moment or symbolic image that describes the PR
+  intent.
+- Maps, diagrams, dossiers, route lines, labels, and artifacts can appear as
+  props inside the scene, but the output should read as an image rather than a
+  dense infographic.
+- Take creative liberty with layout and styling.
+- The hard rule: the meaning must be readable and clearly hierarchical.
+- Keep labels plain-language and technical when labels are used.
+
+CONTENT:
+1. "<section>"
+  - <evidence-grounded outcome>
+  - <evidence-grounded outcome>
+
+2. "<section>"
+  - <evidence-grounded outcome>
+  - <evidence-grounded outcome>
+
+METRICS:
+- <metric>
+- <metric>
+
+STYLE DIRECTION:
+- Upscaled editorial, high contrast, anti-aliased text, smooth edges.
+- Let the category's visual DNA drive the composition.
+- Use genre/category cues only; do not use copyrighted characters, logos, named
+  fictional universes, direct band logos, album art, or celebrity likenesses.
+
+DO NOT:
+- Make text unreadable or let decoration obscure content.
+- Render a text-heavy infographic, dashboard, flowchart, timeline strip,
+  checklist, bullet-list panel, or dense explanatory diagram.
+- Use crunchy low-resolution pixel art.
+- Invent facts not present in the evidence pack.
+```
+
+## Writing Rules
+
+- Keep each bullet specific and evidence-grounded.
+- Prefer outcome language over implementation trivia.
+- Default to three or four sections; never exceed five.
+- Give proportionally more space to dominant changes.
+- Keep the final prompt short, energetic, and readable.
@@ -0,0 +1,42 @@
+# Style Balance Rubric
+
+## Core Principle
+
+Be bold, not confusing. The selected BM style category should structure the
+visual through a readable image-first composition, not decorate a generic grid.
+Use an editorial scene, poster, painting, photograph, cover, staged artifact, or
+tableau that turns the PR intent into a visual moment.
+
+## Required Traits
+
+- Anti-aliased typography
+- Smooth edges
+- High contrast between text and background
+- Plain-language section labels
+- Clear composition backbone: staged scene, editorial poster, painting,
+  photograph, symbolic tableau, hero artifact, dossier, mission room, or route
+  embodied as part of the scene
+- A single coherent BM style category, expressed through original visual cues
+
+## Reject Or Rewrite If
+
+- Content text is unreadable.
+- The prompt lacks a composition backbone.
+- The prompt over-prescribes exact panel positions or a rigid grid.
+- The style leans into crunchy low-resolution pixelation.
+- Copy uses lore-heavy references instead of engineering meaning.
+- The prompt uses copyrighted characters, logos, named fictional universes,
+  direct band logos, album art, or celebrity likenesses.
+
+## Creative Integration Patterns
+
+- Use category-native map details to organize content: textbook diagrams,
+  literary journeys, quest maps, tour posters, mission-control routes, stage
+  blocking, mythic constellations, star charts, mission trajectories, case
+  boards, or civic plans as props inside the image.
+- Recreate a scene, editorial poster, painting, photograph, cover, artifact, or
+  tableau instead of sectioned bullets.
+- Map engineering metrics to visual counters, route progress, or status boards
+  only when they naturally belong in the scene.
+- Let headers and accents borrow from the selected style.
+- Keep atmospheric details behind or around content, never over it.
@@ -0,0 +1,114 @@
+---
+name: pr-create
+description: Use when creating or updating a Basic Memory pull request from Codex with BM Bossbot merge-gate monitoring.
+---
+
+# Create A Basic Memory PR
+
+Create or update a pull request for the current branch, then wait for BM
+Bossbot to approve the latest head SHA. This skill never merges a PR.
+
+## Inputs
+
+- Optional `<theme>`: free-form visual direction for the non-gating PR
+  image. Example: `$pr-create "Italian movie poster"`.
+- Treat `<theme>` as style guidance only. It must not affect PR readiness,
+  BM Bossbot review, status checks, or merge behavior.
+
+## How To Use
+
+Ask Codex to use the skill from a feature branch:
+
+```text
+$pr-create
+$pr-create "Italian movie poster"
+$pr-create "80's action movies"
+```
+
+Use the plain form when you only want the PR workflow. Pass a theme when you
+want the non-gating image to lean toward a particular visual direction. The
+theme can be specific ("Rembrandt-inspired approval scene") or broad ("let the
+model choose from BM categories").
+
+## What Happens
+
+1. Codex checks the branch, local verification, GitHub auth, commit sign-offs,
+   and semantic PR title shape.
+2. Codex pushes the branch, creates or reuses the PR, and adds the optional
+   `BM_INFOGRAPHIC_THEME` block when a theme was supplied.
+3. BM Bossbot runs from trusted base code, reviews sanitized PR metadata and
+   diff context, and sets the required `BM Bossbot Approval` status for the
+   exact head SHA.
+4. If approval succeeds, BM Bossbot may publish a non-gating image block and a
+   provenance block:
+
+   ```markdown
+   <!-- BM_INFOGRAPHIC_PROVENANCE:start -->
+   ...
+   <!-- BM_INFOGRAPHIC_PROVENANCE:end -->
+   ```
+
+   The provenance records the image mode, theme source, selected visual
+   direction, and image settings. It is for review/debugging context only.
+5. Codex reports the PR URL, head SHA, checks watched, verification run, and BM
+   Bossbot verdict.
+
+The skill never merges, never enables auto-merge, and never treats the image or
+provenance block as a gate. The only required merge signal is the
+`BM Bossbot Approval` status on the current PR head SHA.
+
+## Preflight
+
+1. Confirm the repo and branch:
+   - `git status --short --branch`
+   - stop if detached or on `main`
+   - keep unrelated user changes intact
+
+2. Confirm GitHub access:
+   - `gh auth status`
+   - `gh repo view --json nameWithOwner,defaultBranchRef,url`
+
+3. Check PR readiness:
+   - commits are signed off with `git commit -s`
+   - title uses the repo semantic format
+   - local verification appropriate to the change has run
+
+## Create Or Reuse
+
+1. Push the branch:
+   - `git push -u origin HEAD`
+
+2. Check for an existing PR:
+   - `gh pr view --json number,url,headRefOid,mergeStateStatus,statusCheckRollup`
+
+3. If no PR exists, create one:
+   - `gh pr create --fill`
+   - adjust the title if it does not satisfy the semantic PR title workflow
+
+4. If `<theme>` is provided, add or update this managed block in the PR body:
+
+```markdown
+<!-- BM_INFOGRAPHIC_THEME:start -->
+<theme>
+<!-- BM_INFOGRAPHIC_THEME:end -->
+```
+
+Keep the rest of the PR body intact. The theme is non-gating image guidance
+only.
+
+5. Do not merge. Do not enable auto-merge.
+
+## Watch The Gate
+
+1. Trigger or wait for `.github/workflows/bm-bossbot.yml`.
+2. Watch the required commit status named `BM Bossbot Approval`.
+3. Treat approval as valid only when it is green for the current `headRefOid`.
+4. If the branch changes after approval, wait for BM Bossbot to review the new
+   head SHA.
+5. If BM Bossbot fails or requests changes, use `$fix-pr-issues`.
+
+## Report
+
+Return the PR URL, current head SHA, checks watched, verification run, and the
+BM Bossbot verdict. Include the image `<theme>` if one was supplied. Be
+explicit when any check is still pending.
@@ -0,0 +1,7 @@
+interface:
+  display_name: "PR Create"
+  short_description: "Create PRs and wait for BM Bossbot"
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#2563EB"
+  default_prompt: "Use $pr-create to create or update this Basic Memory PR and wait for BM Bossbot Approval."
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 24 24" fill="none" stroke="#111827" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M3 12h4l2-6 4 12 2-6h6"/>
+  <path d="M4 20h16"/>
+</svg>
+
@@ -0,0 +1 @@
+../../.agents/skills/basic-machines-review
@@ -0,0 +1,193 @@
+name: BM Bossbot
+
+"on":
+  workflow_run:
+    workflows:
+      - Tests
+    types:
+      - completed
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to review
+        required: true
+  # Review-thread activity re-evaluates the approval status without re-running
+  # the full LLM review: new feedback flips the gate to failure, resolving the
+  # last thread restores a previously earned approval for the same head SHA.
+  pull_request_review:
+    types:
+      - submitted
+  pull_request_review_comment:
+    types:
+      - created
+  pull_request_review_thread:
+    types:
+      - resolved
+      - unresolved
+
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+  issues: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  BM_BOSSBOT_STATUS_CONTEXT: "BM Bossbot Approval"
+
+jobs:
+  review:
+    name: BM Bossbot Review
+    # Job-level concurrency (not workflow-level): thread-recheck events for the
+    # same PR must never cancel an in-flight review run, and vice versa.
+    concurrency:
+      group: bm-bossbot-review-${{ github.event.workflow_run.pull_requests[0].number || inputs.pr_number }}
+      cancel-in-progress: true
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.pull_requests[0].number != ''
+      )
+    runs-on: ubuntu-latest
+    outputs:
+      pr_number: ${{ steps.pr.outputs.pr_number }}
+      should_review: ${{ steps.pr.outputs.should_review }}
+
+    steps:
+      - name: Checkout trusted base ref
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Normalize PR event
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          event_file="${RUNNER_TEMP}/bm-bossbot-event.json"
+          should_review=true
+
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            pr_number="${{ inputs.pr_number }}"
+            tested_sha=""
+          else
+            pr_number="$(jq -r '.workflow_run.pull_requests[0].number // ""' "${GITHUB_EVENT_PATH}")"
+            tested_sha="$(jq -r '.workflow_run.head_sha // ""' "${GITHUB_EVENT_PATH}")"
+          fi
+
+          gh api "repos/${GITHUB_REPOSITORY}/pulls/${pr_number}" > "${RUNNER_TEMP}/pull.json"
+          current_head_sha="$(jq -r '.head.sha' "${RUNNER_TEMP}/pull.json")"
+          draft="$(jq -r '.draft' "${RUNNER_TEMP}/pull.json")"
+
+          if [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
+            tests_run_id="$(
+              gh api -X GET "repos/${GITHUB_REPOSITORY}/actions/workflows/test.yml/runs" \
+                -f event=push \
+                -f head_sha="${current_head_sha}" \
+                -f status=completed \
+                --jq '[.workflow_runs[] | select(.conclusion == "success")][0].id // ""'
+            )"
+            if [ -z "${tests_run_id}" ]; then
+              should_review=false
+              echo "BM Bossbot skipped PR ${pr_number}: no successful Tests workflow for ${current_head_sha}."
+            fi
+          fi
+
+          if [ "${draft}" = "true" ]; then
+            should_review=false
+            echo "BM Bossbot skipped PR ${pr_number}: draft pull request."
+          fi
+
+          if [ -n "${tested_sha}" ] && [ "${tested_sha}" != "${current_head_sha}" ]; then
+            should_review=false
+            echo "BM Bossbot skipped PR ${pr_number}: Tests passed for ${tested_sha}, but current head is ${current_head_sha}."
+          fi
+
+          jq --arg repo "${GITHUB_REPOSITORY}" \
+            '{repository:{full_name:$repo}, pull_request:{number:.number,title:.title,body:(.body // ""),html_url:.html_url,head:{sha:.head.sha,ref:.head.ref},base:{ref:.base.ref,sha:.base.sha},author_association:.author_association,draft:.draft}}' \
+            "${RUNNER_TEMP}/pull.json" > "${event_file}"
+
+          echo "event_file=${event_file}" >> "${GITHUB_OUTPUT}"
+          echo "pr_number=$(jq -r '.pull_request.number' "${event_file}")" >> "${GITHUB_OUTPUT}"
+          echo "head_sha=$(jq -r '.pull_request.head.sha' "${event_file}")" >> "${GITHUB_OUTPUT}"
+          echo "head_ref=$(jq -r '.pull_request.head.ref' "${event_file}")" >> "${GITHUB_OUTPUT}"
+          echo "author_association=$(jq -r '.pull_request.author_association // ""' "${event_file}")" >> "${GITHUB_OUTPUT}"
+          echo "tested_sha=${tested_sha}" >> "${GITHUB_OUTPUT}"
+          echo "should_review=${should_review}" >> "${GITHUB_OUTPUT}"
+
+      - name: Classify PR author
+        id: trust
+        if: steps.pr.outputs.should_review == 'true'
+        env:
+          AUTHOR_ASSOCIATION: ${{ steps.pr.outputs.author_association }}
+        run: |
+          set -euo pipefail
+          case "${AUTHOR_ASSOCIATION}" in
+            OWNER|MEMBER|COLLABORATOR)
+              trusted_author=true
+              ;;
+            *)
+              trusted_author=false
+              ;;
+          esac
+          echo "trusted_author=${trusted_author}" >> "${GITHUB_OUTPUT}"
+          echo "author_association=${AUTHOR_ASSOCIATION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Mark BM Bossbot approval pending
+        if: steps.pr.outputs.should_review == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          uv run --script scripts/bm_bossbot_status.py pending \
+            --event "${{ steps.pr.outputs.event_file }}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+      - name: Finalize BM Bossbot approval
+        if: always() && steps.pr.outputs.should_review == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          uv run --script scripts/bm_bossbot_status.py finalize \
+            --event "${{ steps.pr.outputs.event_file }}" \
+            --trusted "${{ steps.trust.outputs.trusted_author }}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+  recheck:
+    name: BM Bossbot Thread Recheck
+    if: |
+      github.event_name == 'pull_request_review' ||
+      github.event_name == 'pull_request_review_comment' ||
+      github.event_name == 'pull_request_review_thread'
+    runs-on: ubuntu-latest
+    # Job-level concurrency: collapse bursts of thread events for one PR while
+    # staying isolated from the review job's group so neither cancels the other.
+    concurrency:
+      group: bm-bossbot-recheck-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - name: Checkout trusted base ref
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          fetch-depth: 1
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Re-evaluate approval from review-thread state
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          uv run --script scripts/bm_bossbot_status.py recheck \
+            --pr-number "${{ github.event.pull_request.number }}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --run-url "${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
@@ -1,26 +1,18 @@
 name: Claude Code Review

-on:
-  pull_request:
-    types: [opened, synchronize]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+"on":
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to review manually
+        required: true

 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

 jobs:
  claude-review:
-    # Only run for organization members and collaborators
-    if: |
-      github.event.pull_request.author_association == 'OWNER' ||
-      github.event.pull_request.author_association == 'MEMBER' ||
-      github.event.pull_request.author_association == 'COLLABORATOR'
-
+    if: inputs.pr_number != ''
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -43,7 +35,14 @@ jobs:
          track_progress: true  # Enable visual progress tracking
          allowed_bots: '*'
          prompt: |
-            Review this Basic Memory PR against our team checklist:
+            Review Basic Memory PR #${{ inputs.pr_number }} as an advisory manual review.
+
+            Use `gh pr view ${{ inputs.pr_number }}` and related `gh pr`/`gh api`
+            commands to inspect the pull request. Do not merge the PR and do not
+            treat this advisory review as the required merge gate. BM Bossbot owns
+            the required `BM Bossbot Approval` status.
+
+            Review the PR against our team checklist:

            ## Code Quality & Standards
            - [ ] Follows Basic Memory's coding conventions in CLAUDE.md
@@ -13,9 +13,10 @@ env:

 jobs:
  docker:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
    permissions:
      contents: read
+      id-token: write
      packages: write

    steps:
@@ -24,10 +25,8 @@ jobs:
        with:
          fetch-depth: 0

-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-        with:
-          platforms: linux/amd64,linux/arm64
+      - name: Set up Depot
+        uses: depot/setup-action@v1

      - name: Log in to GitHub Container Registry
        uses: docker/login-action@v4
@@ -49,13 +48,12 @@ jobs:
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push Docker image
-        uses: docker/build-push-action@v7
+        uses: depot/build-push-action@v1
        with:
+          project: ${{ vars.DEPOT_BASIC_MEMORY_PROJECT_ID || vars.DEPOT_PROJECT_ID }}
          context: .
          file: ./Dockerfile
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
@@ -13,12 +13,15 @@ on:

 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  # Required CI records pytest-testmon data but still runs the full selected suite.
+  # The selective mode stays on explicit developer flows such as `just testmon`.
+  BASIC_MEMORY_TESTMON_FLAGS: "--testmon-noselect"

 jobs:
  static-checks:
    name: Static Checks (Python 3.12)
    timeout-minutes: 20
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04

    steps:
      - uses: actions/checkout@v6
@@ -60,10 +63,12 @@ jobs:
      fail-fast: false
      matrix:
        include:
-          - os: ubuntu-latest
+          - os: depot-ubuntu-24.04
            python-version: "3.12"
-          - os: ubuntu-latest
+          - os: depot-ubuntu-24.04
            python-version: "3.13"
+          # Python 3.14 unit tests are the longest full-suite slice; keep this
+          # one on GitHub-hosted runners after Depot terminated it mid-suite.
          - os: ubuntu-latest
            python-version: "3.14"
          - os: windows-latest
@@ -87,6 +92,19 @@ jobs:

      - uses: extractions/setup-just@v4

+      - name: Cache pytest-testmon results
+        uses: actions/cache@v4
+        with:
+          path: |
+            .testmondata
+            .testmondata-shm
+            .testmondata-wal
+          key: ${{ runner.os }}-testmon-sqlite-unit-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-testmon-sqlite-unit-py${{ matrix.python-version }}-${{ github.ref_name }}-
+            ${{ runner.os }}-testmon-sqlite-unit-py${{ matrix.python-version }}-main-
+            ${{ runner.os }}-testmon-sqlite-unit-py${{ matrix.python-version }}-
+
      - name: Create virtual env
        run: |
          uv venv
@@ -106,11 +124,11 @@ jobs:
      fail-fast: false
      matrix:
        include:
-          - os: ubuntu-latest
+          - os: depot-ubuntu-24.04
            python-version: "3.12"
-          - os: ubuntu-latest
+          - os: depot-ubuntu-24.04
            python-version: "3.13"
-          - os: ubuntu-latest
+          - os: depot-ubuntu-24.04
            python-version: "3.14"
          - os: windows-latest
            python-version: "3.12"
@@ -133,6 +151,19 @@ jobs:

      - uses: extractions/setup-just@v4

+      - name: Cache pytest-testmon results
+        uses: actions/cache@v4
+        with:
+          path: |
+            .testmondata
+            .testmondata-shm
+            .testmondata-wal
+          key: ${{ runner.os }}-testmon-sqlite-integration-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-testmon-sqlite-integration-py${{ matrix.python-version }}-${{ github.ref_name }}-
+            ${{ runner.os }}-testmon-sqlite-integration-py${{ matrix.python-version }}-main-
+            ${{ runner.os }}-testmon-sqlite-integration-py${{ matrix.python-version }}-
+
      - name: Create virtual env
        run: |
          uv venv
@@ -153,9 +184,14 @@ jobs:
      matrix:
        include:
          - python-version: "3.12"
+            os: depot-ubuntu-24.04
          - python-version: "3.13"
+            os: depot-ubuntu-24.04
+          # Match the SQLite unit slice: this full Python 3.14 path outlived
+          # the Depot runner and was terminated mid-suite.
          - python-version: "3.14"
-    runs-on: ubuntu-latest
+            os: ubuntu-latest
+    runs-on: ${{ matrix.os }}
    services:
      postgres:
        image: pgvector/pgvector:pg16
@@ -190,6 +226,19 @@ jobs:

      - uses: extractions/setup-just@v4

+      - name: Cache pytest-testmon results
+        uses: actions/cache@v4
+        with:
+          path: |
+            .testmondata
+            .testmondata-shm
+            .testmondata-wal
+          key: ${{ runner.os }}-testmon-postgres-unit-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-testmon-postgres-unit-py${{ matrix.python-version }}-${{ github.ref_name }}-
+            ${{ runner.os }}-testmon-postgres-unit-py${{ matrix.python-version }}-main-
+            ${{ runner.os }}-testmon-postgres-unit-py${{ matrix.python-version }}-
+
      - name: Create virtual env
        run: |
          uv venv
@@ -212,7 +261,7 @@ jobs:
          - python-version: "3.12"
          - python-version: "3.13"
          - python-version: "3.14"
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
    services:
      postgres:
        image: pgvector/pgvector:pg16
@@ -247,6 +296,19 @@ jobs:

      - uses: extractions/setup-just@v4

+      - name: Cache pytest-testmon results
+        uses: actions/cache@v4
+        with:
+          path: |
+            .testmondata
+            .testmondata-shm
+            .testmondata-wal
+          key: ${{ runner.os }}-testmon-postgres-integration-py${{ matrix.python-version }}-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-testmon-postgres-integration-py${{ matrix.python-version }}-${{ github.ref_name }}-
+            ${{ runner.os }}-testmon-postgres-integration-py${{ matrix.python-version }}-main-
+            ${{ runner.os }}-testmon-postgres-integration-py${{ matrix.python-version }}-
+
      - name: Create virtual env
        run: |
          uv venv
@@ -262,7 +324,7 @@ jobs:
  test-semantic:
    name: Test Semantic (Python 3.12)
    timeout-minutes: 45
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04

    steps:
      - uses: actions/checkout@v6
@@ -281,6 +343,19 @@ jobs:

      - uses: extractions/setup-just@v4

+      - name: Cache pytest-testmon results
+        uses: actions/cache@v4
+        with:
+          path: |
+            .testmondata
+            .testmondata-shm
+            .testmondata-wal
+          key: ${{ runner.os }}-testmon-semantic-py3.12-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-testmon-semantic-py3.12-${{ github.ref_name }}-
+            ${{ runner.os }}-testmon-semantic-py3.12-main-
+            ${{ runner.os }}-testmon-semantic-py3.12-
+
      - name: Create virtual env
        run: |
          uv venv
@@ -49,7 +49,7 @@ ENV/
 /docs/.obsidian/
 /examples/.obsidian/
 /examples/.basic-memory/
-
+/docs/assets

 # claude action
 claude-output
@@ -108,13 +108,34 @@ Before opening or updating a PR, run the checks that mirror the common required
 - Follow the repository pattern for data access
 - Tools communicate to api routers via the httpx ASGI client (in process)

+### Programming Style
+
+See [docs/ENGINEERING_STYLE.md](docs/ENGINEERING_STYLE.md) for the fuller house style. The
+short version for agents:
+
+- Prefer type-safe, explicit designs over object-heavy indirection. Use Python 3.12 `type`
+  aliases, full annotations, and narrow `Protocol`s when a caller only needs a capability.
+- Use dataclasses for internal value objects and operation results; use Pydantic v2 at API,
+  CLI, MCP, and persistence boundaries where validation and serialization matter.
+- Keep async boundaries obvious. Resource-owning code should use context managers, propagate
+  cancellation, and avoid hidden background work unless the lifecycle is explicit.
+- Fail fast. Do not add silent fallback logic, broad exception swallowing, speculative
+  `getattr`, or casts that hide an unclear model shape.
+- Keep control flow simple and local. Push branching decisions up, keep leaf helpers focused,
+  and name values after the domain concept they carry.
+- Use evidence-first testing. Add or update meaningful regression tests for bugs and risky
+  behavior, prefer real code paths over mocks, and run the narrowest command that proves the
+  change before widening verification.
+- Comments should explain why a branch, invariant, or constraint exists. Avoid comments that
+  merely narrate obvious code.
+
 ### Code Change Guidelines

 - **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits
 - **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness
- **No speculative getattr**: Never use `getattr(obj, "attr", default)` when unsure about attribute names. Check the class definition or source code first
- **Fail fast**: Write code with fail-fast logic by default. Do not swallow exceptions with errors or warnings
- **No fallback logic**: Do not add fallback logic unless explicitly told to and agreed with the user
+- **House style is canonical**: Follow the Programming Style section above for type-safe,
+  fail-fast code; do not hide unclear models with speculative attributes, broad exception
+  handling, casts, or unapproved fallback logic
 - **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.

 ### Literate Programming Style
@@ -348,6 +369,13 @@ See `.claude/commands/release/release.md` (and `beta.md`, `release-check.md`, `c
 - Manage snapshots: `basic-memory cloud snapshot [create|list|delete|show|browse]`
 - Restore from snapshot: `basic-memory cloud restore <path> --snapshot <id>`

+**Cloud Sync Commands (Personal and Team workspaces):**
+- Fetch cloud changes (cloud -> local): `basic-memory cloud pull --name "name"` (Team-safe; additive, never deletes local)
+- Upload local changes (local -> cloud): `basic-memory cloud push --name "name"` (Team-safe; additive, never deletes cloud)
+- Resolve conflicts on push/pull: `--on-conflict [fail|keep-local|keep-cloud|keep-both]` (default `fail` lists conflicts and aborts, git-style)
+- One-way mirror (local -> cloud): `basic-memory cloud sync --name "name"` (Personal workspaces only; deletes cloud files missing locally)
+- Two-way mirror (local <-> cloud): `basic-memory cloud bisync --name "name"` (Personal workspaces only)
+
 ### MCP Capabilities

 - Basic Memory exposes these MCP tools to LLMs:
@@ -216,14 +216,14 @@ Source: [`plugins/claude-code`](plugins/claude-code).
 ### Shared skills

 Framework-agnostic `SKILL.md` files live in [`skills/`](skills). If your
-Skills CLI supports subpath installs:
+Skills CLI supports repository subdirectory sources:

 ```bash
-npx skills add basicmachines-co/basic-memory --path skills
+npx skills add basicmachines-co/basic-memory/skills
 ```

-If it does not, copy the `memory-*` directories from `skills/` into your
-agent's skills directory as a temporary Phase 1 install path.
+If your installed Skills CLI cannot load that source, update the CLI or copy
+the `memory-*` directories from `skills/` into your agent's skills directory.

 ### Hermes

@@ -0,0 +1,64 @@
+# Basic Memory Engineering Style
+
+Style is how we make code easier to verify. Prefer explicit, typed, local-first code that
+preserves the file system as the source of truth while keeping the database, API, and MCP
+surfaces in sync.
+
+## Design Center
+
+- Basic Memory is local-first. Markdown files are the durable source; SQLite/Postgres indexes
+  are derived state that should be rebuilt or reconciled from files when needed.
+- Keep the existing boundary order: CLI/MCP/API entrypoints compose dependencies, services own
+  business behavior, repositories own database access, and file services own filesystem writes.
+- MCP tools should remain atomic and composable. They should call API routers through typed MCP
+  clients, not reach around into services.
+- Prefer small, explicit abstractions that match a real domain boundary. Avoid object
+  hierarchies when a function, dataclass, type alias, or protocol describes the concept better.
+
+## Types And Data
+
+- Use full type annotations and Python 3.12 syntax. Introduce `type` aliases for repeated
+  structured shapes, callback signatures, or domain concepts that would otherwise become
+  anonymous `dict[str, Any]` values.
+- Use dataclasses for internal values, operation inputs, and service results. Prefer
+  `frozen=True` when the value should not change and `slots=True` when identity/dynamic
+  attributes are not needed.
+- Use Pydantic v2 at boundaries that validate, serialize, or deserialize data: API payloads,
+  CLI/MCP schemas, configuration, and persistence-adjacent schemas.
+- Use narrow `Protocol`s when a caller needs a capability rather than a concrete repository or
+  service. Keep protocols small enough that fake implementations in tests are obvious.
+- Avoid speculative `getattr`, broad casts, or `Any` as a way to paper over uncertainty. Read
+  the model or schema definition and make the type relationship explicit.
+
+## Control Flow And Resources
+
+- Fail fast when an invariant is broken. Do not swallow exceptions, add warning-only error
+  handling, or introduce fallback behavior unless the user explicitly agrees to that behavior.
+- Keep control flow simple and close to the domain decision. Push `if` statements up into the
+  function that owns orchestration; keep leaf helpers focused on computation or one side effect.
+- Make async/resource boundaries visible with context managers and explicit lifecycles. Do not
+  start background work without a clear owner, cancellation story, and verification path.
+- Keep file mutations centralized through the existing file utilities/services so checksum,
+  atomic write, and index synchronization behavior stays coherent.
+
+## Testing And Verification
+
+- Use evidence-first testing, not mechanical TDD. For bugs and risky behavior, add or update a
+  regression test that would catch the failure. For small documentation-only edits, use the
+  relevant doc/repo hygiene checks.
+- Prefer tests that exercise real code paths. Use mocks, doubles, or `monkeypatch` only when
+  the external boundary would be slow, nondeterministic, or impossible to trigger directly.
+- Keep coverage at 100% for new code. Use `# pragma: no cover` only for code that would require
+  disproportionate mocking and is covered through an integration or runtime path.
+- Start with targeted commands, then widen as risk grows: focused pytest, `just fast-check`,
+  `just doctor`, package checks for agent packaging changes, and full SQLite/Postgres gates
+  when behavior crosses shared boundaries.
+
+## Comments And Names
+
+- Name values after the domain concept they carry: project, entity, permalink, tenant, route,
+  checksum, observation, relation, batch, or index state.
+- Comments should say why a branch, invariant, retry, lifecycle, or compatibility constraint
+  exists. Section headers are useful when a function or file has clear phases.
+- Avoid comments that restate the code. If a comment cannot explain a decision, simplify the
+  code or improve the name instead.
@@ -8,9 +8,25 @@ The cloud CLI enables you to:
 - **Authenticate cloud access** - OAuth/API key credentials are stored locally for cloud operations
 - **Project-scoped sync** - Each project independently manages its sync configuration
 - **Explicit operations** - Sync only what you want, when you want
- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
+- **Team-safe push/pull** - Additive, git-style transfers that work on shared Team workspaces
+- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync (Personal workspaces)
 - **Offline access** - Work locally, sync when ready

+### Personal vs Team workspaces
+
+The transfer commands fall into two groups:
+
+| Command | Direction | Behavior | Personal | Team |
+|---|---|---|---|---|
+| `bm cloud pull` | cloud → local | **additive** — never deletes local | ✅ | ✅ |
+| `bm cloud push` | local → cloud | **additive** — never deletes cloud | ✅ | ✅ |
+| `bm cloud sync` | local → cloud | **mirror** — deletes cloud files missing locally | ✅ | ❌ |
+| `bm cloud bisync` | local ↔ cloud | **mirror** — two-way, deletes on both sides | ✅ | ❌ |
+
+`sync` and `bisync` are mirror operations: one local tree becomes authoritative and files missing on the other side get deleted. That is correct for a Personal workspace (one user, one source of truth) but unsafe on a shared Team bucket, where it could delete a teammate's files. On Team workspaces these commands exit early with a clear error and point you at `push`/`pull`.
+
+`push` and `pull` are additive (they use `rclone copy`, which never deletes on the destination), so they are safe on both Personal and Team workspaces.
+
 ## Prerequisites

 Before using Basic Memory Cloud, you need:
@@ -55,8 +71,8 @@ bm project add work --cloud --local-path ~/work-notes
 bm project add temp --cloud  # No local sync

 # Now you can sync individually (after initial --resync):
-bm project bisync --name research
-bm project bisync --name work
+bm cloud bisync --name research
+bm cloud bisync --name work
 # temp stays cloud-only
 ```

@@ -137,10 +153,10 @@ Establish the initial sync baseline. **Best practice:** Always preview with `--d

 ```bash
 # Step 1: Preview the initial sync (recommended)
-bm project bisync --name research --resync --dry-run
+bm cloud bisync --name research --resync --dry-run

 # Step 2: If all looks good, run the actual sync
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 **What happens under the covers:**
@@ -167,7 +183,7 @@ This will effectively make both Path1 and Path2 filesystems contain a matching s
 After the first sync, just run bisync without `--resync`:

 ```bash
-bm project bisync --name research
+bm cloud bisync --name research
 ```

 **What happens:**
@@ -235,7 +251,7 @@ bm project add research --cloud --local-path ~/Documents/research
 - Stores sync config in `~/.basic-memory/config.json`
 - Prepares for bisync (but doesn't sync yet)

-**Result:** Project ready to sync. Run `bm project bisync --name research --resync` to establish baseline.
+**Result:** Project ready to sync. Run `bm cloud bisync --name research --resync` to establish baseline.

 **Use case 3: Add sync to existing cloud project**

@@ -294,18 +310,98 @@ For MCP stdio, routing is always local.

 ### Understanding the Sync Commands

-**There are three sync-related commands:**
+**There are five sync-related commands:**

-1. `bm project sync` - One-way: local → cloud (make cloud match local)
-2. `bm project bisync` - Two-way: local ↔ cloud (recommended)
-3. `bm project check` - Verify files match (no changes)
+| Command | Direction | Workspace | Summary |
+|---|---|---|---|
+| `bm cloud pull` | cloud → local | Personal + Team | Fetch cloud changes, additively (git-style) |
+| `bm cloud push` | local → cloud | Personal + Team | Upload local changes, additively (git-style) |
+| `bm cloud sync` | local → cloud | Personal only | One-way mirror (cloud becomes identical to local) |
+| `bm cloud bisync` | local ↔ cloud | Personal only | Two-way mirror (recommended for solo use) |
+| `bm cloud check` | — | Personal + Team | Verify files match (no changes) |

-### One-Way Sync: Local → Cloud
+If you collaborate on a shared Team workspace, use **`push`/`pull`** (see [Team Workspaces](#team-workspaces-push--pull-additive-git-style)). If you are the only writer (a Personal workspace), the mirror commands `sync`/`bisync` give you a single source of truth.
+
+### Team Workspaces: push / pull (additive, git-style)
+
+`push` and `pull` are the Team-safe transfer commands. They model `git push` / `git pull`:
+
+- **`bm cloud pull`** fetches changes from the cloud into your local directory.
+- **`bm cloud push`** uploads your local changes to the cloud.
+
+Both use `rclone copy`, so they are **additive — they never delete on the destination**. A conflict (a file that differs on both sides) is never resolved silently: by default the command aborts and lists the conflicting files, exactly like git refusing to clobber your changes.
+
+#### Pull: fetch cloud changes
+
+```bash
+# Preview first (recommended)
+bm cloud pull --name research --dry-run
+
+# Fetch new/changed cloud files into local
+bm cloud pull --name research
+```
+
+**What happens:**
+1. Compares cloud and local with `rclone check`
+2. Downloads files that are new or changed on the cloud
+3. Leaves your local-only files untouched (never deletes local)
+4. If any file differs on both sides, aborts and lists the conflicts (unless you pass `--on-conflict`)
+
+#### Push: upload local changes
+
+```bash
+bm cloud push --name research --dry-run
+bm cloud push --name research
+```
+
+**What happens:**
+1. Compares local and cloud with `rclone check`
+2. Uploads files that are new or changed locally
+3. Leaves cloud-only files untouched (never deletes cloud)
+4. If any file differs on both sides, aborts and lists the conflicts — pull first, like a rejected `git push`
+
+#### Resolving conflicts
+
+When `push`/`pull` reports conflicts, re-run with `--on-conflict` to choose how differing files are handled. The value names exactly what survives, so it reads the same in both directions:
+
+| `--on-conflict` | Behavior |
+|---|---|
+| `fail` *(default)* | List the conflicting files and exit without transferring anything |
+| `keep-cloud` | Take the cloud version (pull: overwrite local; push: skip those files) |
+| `keep-local` | Keep the local version (pull: skip those files; push: overwrite cloud) |
+| `keep-both` | Keep both — write the incoming version beside the existing one as `name.conflict-<date>.md` |
+
+```bash
+# A teammate edited notes you also changed locally — pull reports a conflict:
+bm cloud pull --name research
+# pull aborted: 1 file(s) differ between local and cloud.
+#   * notes/decisions.md
+# Re-run with one of: --on-conflict keep-cloud | keep-local | keep-both
+
+# Take the cloud copy:
+bm cloud pull --name research --on-conflict keep-cloud
+
+# Or keep both versions to merge by hand:
+bm cloud pull --name research --on-conflict keep-both
+```
+
+#### Limitations
+
+`push`/`pull` are deliberately simple, conflict-aware byte transfers — not a full reconciler. Without a sync baseline:
+
+- **Deletions are not propagated.** A note deleted on one side is not removed from the other (we cannot tell an intentional delete from a file the other side never had). This is surfaced in the command output.
+- **Every divergence is treated as a conflict.** We cannot tell a teammate's edit from your stale copy, so any differing file prompts a decision rather than auto-resolving.
+
+For conflict-aware *editing*, write through the MCP/API tools (which merge at the note level). A Team-safe bidirectional reconciler with a real baseline is tracked in [issue #862](https://github.com/basicmachines-co/basic-memory/issues/862).
+
+### One-Way Sync: Local → Cloud (Personal only)

 **Use case:** You made changes locally and want to push to cloud (overwrite cloud).

+> **Personal workspaces only.** `sync` is a destructive mirror — it deletes cloud files that are not present locally. On a Team workspace it would delete a teammate's files, so it is blocked there. Use `bm cloud push` (additive) on Team workspaces.
+
 ```bash
-bm project sync --name research
+bm cloud sync --name research
 ```

 **What happens:**
@@ -321,16 +417,18 @@ bm project sync --name research
 - You want to force cloud to match local
 - You don't care about cloud changes

-### Two-Way Sync: Local ↔ Cloud (Recommended)
+### Two-Way Sync: Local ↔ Cloud (Personal only, recommended for solo use)

 **Use case:** You edit files both locally and in cloud UI, want both to stay in sync.

+> **Personal workspaces only.** `bisync` is a two-way mirror that can delete and overwrite on both sides. It is blocked on Team workspaces — use `bm cloud pull` then `bm cloud push` there. A Team-safe bidirectional reconciler is tracked separately ([issue #862](https://github.com/basicmachines-co/basic-memory/issues/862)).
+
 ```bash
 # First time - establish baseline
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync

 # Subsequent syncs
-bm project bisync --name research
+bm cloud bisync --name research
 ```

 **What happens:**
@@ -349,7 +447,7 @@ echo "Local change" > ~/Documents/research/notes.md
 # Cloud now has: "Cloud change"

 # Run bisync
-bm project bisync --name research
+bm cloud bisync --name research

 # Result: Newer file wins (based on modification time)
 # If cloud was more recent, cloud version kept
@@ -366,7 +464,7 @@ bm project bisync --name research
 **Use case:** Check if local and cloud match without making changes.

 ```bash
-bm project check --name research
+bm cloud check --name research
 ```

 **What happens:**
@@ -378,7 +476,7 @@ bm project check --name research

 ```bash
 # One-way check (faster)
-bm project check --name research --one-way
+bm cloud check --name research --one-way
 ```

 ### Preview Changes (Dry Run)
@@ -386,7 +484,7 @@ bm project check --name research --one-way
 **Use case:** See what would change without actually syncing.

 ```bash
-bm project bisync --name research --dry-run
+bm cloud bisync --name research --dry-run
 ```

 **What happens:**
@@ -432,20 +530,20 @@ bm project add work --cloud --local-path ~/work-notes
 bm project add personal --cloud --local-path ~/personal

 # Establish baselines
-bm project bisync --name research --resync
-bm project bisync --name work --resync
-bm project bisync --name personal --resync
+bm cloud bisync --name research --resync
+bm cloud bisync --name work --resync
+bm cloud bisync --name personal --resync

 # Daily workflow: sync everything
-bm project bisync --name research
-bm project bisync --name work
-bm project bisync --name personal
+bm cloud bisync --name research
+bm cloud bisync --name work
+bm cloud bisync --name personal
 ```

 **Future:** `--all` flag will sync all configured projects:

 ```bash
-bm project bisync --all  # Coming soon
+bm cloud bisync --all  # Coming soon
 ```

 ### Mixed Usage
@@ -462,8 +560,8 @@ bm project add archive --cloud
 bm project add temp-notes --cloud

 # Sync only the configured ones
-bm project bisync --name research
-bm project bisync --name work
+bm cloud bisync --name research
+bm cloud bisync --name work

 # Archive and temp-notes stay cloud-only
 ```
@@ -661,7 +759,7 @@ code ~/.basic-memory/.bmignore
 echo "*.tmp" >> ~/.basic-memory/.bmignore

 # Next sync uses updated patterns
-bm project bisync --name research
+bm cloud bisync --name research
 ```

 ## Troubleshooting
@@ -724,7 +822,7 @@ bm cloud login
 **Solution:**

 ```bash
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 **What this does:**
@@ -747,7 +845,7 @@ bm project bisync --name research --resync
 echo "# Research Notes" > ~/Documents/research/README.md

 # Now run bisync
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 **Why this happens:** Bisync creates listing files that track the state of each side. When both directories are completely empty, these listing files are considered invalid by rclone.
@@ -764,10 +862,10 @@ bm project bisync --name research --resync

 ```bash
 # Clear bisync state
-bm project bisync-reset research
+bm cloud bisync-reset research

 # Re-establish baseline
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 **What this does:**
@@ -787,16 +885,16 @@ bm project bisync --name research --resync

 ```bash
 # Check what would be deleted
-bm project bisync --name research --dry-run
+bm cloud bisync --name research --dry-run

 # If correct, establish new baseline
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 **Solution 2:** Use one-way sync if you know local is correct:

 ```bash
-bm project sync --name research
+bm cloud sync --name research
 ```

 ### Project Not Configured for Sync
@@ -809,7 +907,7 @@ bm project sync --name research

 ```bash
 bm cloud sync-setup research ~/Documents/research
-bm project bisync --name research --resync
+bm cloud bisync --name research --resync
 ```

 ### Connection Issues
@@ -880,20 +978,30 @@ bm project set-local <name>  # Revert project to local mode
 ### File Synchronization

 ```bash
-# One-way sync (local → cloud)
-bm project sync --name <project>
-bm project sync --name <project> --dry-run
-bm project sync --name <project> --verbose
+# Pull: fetch cloud changes (cloud → local) - Personal + Team, additive
+bm cloud pull --name <project>
+bm cloud pull --name <project> --dry-run
+bm cloud pull --name <project> --on-conflict [fail|keep-local|keep-cloud|keep-both]

-# Two-way sync (local ↔ cloud) - Recommended
-bm project bisync --name <project>          # After first --resync
-bm project bisync --name <project> --resync # First time / force baseline
-bm project bisync --name <project> --dry-run
-bm project bisync --name <project> --verbose
+# Push: upload local changes (local → cloud) - Personal + Team, additive
+bm cloud push --name <project>
+bm cloud push --name <project> --dry-run
+bm cloud push --name <project> --on-conflict [fail|keep-local|keep-cloud|keep-both]
+
+# One-way mirror (local → cloud) - Personal workspaces only
+bm cloud sync --name <project>
+bm cloud sync --name <project> --dry-run
+bm cloud sync --name <project> --verbose
+
+# Two-way mirror (local ↔ cloud) - Personal workspaces only
+bm cloud bisync --name <project>          # After first --resync
+bm cloud bisync --name <project> --resync # First time / force baseline
+bm cloud bisync --name <project> --dry-run
+bm cloud bisync --name <project> --verbose

 # Integrity check
-bm project check --name <project>
-bm project check --name <project> --one-way
+bm cloud check --name <project>
+bm cloud check --name <project> --one-way

 # List project files by route
 bm project ls --name <project>          # Default target: local
@@ -909,15 +1017,25 @@ bm project ls --name <project> --cloud --path <subpath>
 1. **Authenticate cloud access** - `bm cloud login`
 2. **Install rclone** - `bm cloud setup`
 3. **Add projects with sync** - `bm project add research --cloud --local-path ~/Documents/research`
-4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
-5. **Establish baseline** - `bm project bisync --name research --resync`
-6. **Daily workflow** - `bm project bisync --name research`
+
+**Personal workspace (solo, mirror) workflow:**
+
+4. **Preview first sync** - `bm cloud bisync --name research --resync --dry-run`
+5. **Establish baseline** - `bm cloud bisync --name research --resync`
+6. **Daily workflow** - `bm cloud bisync --name research`
+
+**Team workspace (shared, additive) workflow:**
+
+4. **Fetch teammates' changes** - `bm cloud pull --name research`
+5. **Upload your changes** - `bm cloud push --name research`
+6. **Resolve conflicts explicitly** - re-run with `--on-conflict keep-cloud|keep-local|keep-both`

 **Key benefits:**
 - ✅ Each project independently syncs (or doesn't)
 - ✅ Projects can live anywhere on disk
 - ✅ Explicit sync operations (no magic)
- ✅ Safe by design (max delete limits, conflict resolution)
+- ✅ Team-safe push/pull that never delete on the destination
+- ✅ Safe by design (max delete limits, conflict resolution, git-style conflict aborts)
 - ✅ Full offline access (work locally, sync when ready)

 **Future enhancements:**
@@ -150,7 +150,7 @@ This plugin ships with workflow-oriented skills that are automatically loaded wh
 No manual installation needed. To update skills or install new ones as they become available:

 ```bash
-npx skills add basicmachines-co/basic-memory --path skills --agent openclaw
+npx skills add basicmachines-co/basic-memory/skills --agent openclaw
 ```

 See the canonical source at [`basic-memory/skills`](../../skills).
@@ -1,5 +1,9 @@
 # Basic Memory - Modern Command Runner

+TESTMON_FLAGS := env_var_or_default("BASIC_MEMORY_TESTMON_FLAGS", "--testmon-noselect")
+TESTMON_SELECT_FLAGS := env_var_or_default("BASIC_MEMORY_TESTMON_SELECT_FLAGS", "--testmon --testmon-forceselect")
+TESTMON_REFRESH_FLAGS := env_var_or_default("BASIC_MEMORY_TESTMON_REFRESH_FLAGS", "--testmon-noselect")
+
 # Install dependencies
 install:
    uv sync
@@ -35,40 +39,56 @@ test-sqlite: test-unit-sqlite test-int-sqlite
 test-postgres: test-unit-postgres test-int-postgres

 # Run unit tests against SQLite
-test-unit-sqlite:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov tests
+test-unit-sqlite: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=unit-sqlite tests

 # Run unit tests against Postgres
-test-unit-postgres:
-    BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov tests
+test-unit-postgres: testmon-seed
+    BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=unit-postgres tests

-# Run integration tests against SQLite (excludes semantic benchmarks — use just test-semantic)
-test-int-sqlite:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int
+# Run integration tests against SQLite (excludes semantic tests and on-demand benchmarks —
+# use just test-semantic / run benchmark files explicitly)
+test-int-sqlite: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=int-sqlite -m "not semantic and not benchmark" test-int

 # Run integration tests against Postgres
 # Note: Uses timeout due to FastMCP Client + asyncpg cleanup hang (tests pass, process hangs on exit)
 # See: https://github.com/jlowin/fastmcp/issues/1311
-test-int-postgres:
+test-int-postgres: testmon-seed
    #!/usr/bin/env bash
    set -euo pipefail
    # Use gtimeout (macOS/Homebrew) or timeout (Linux)
    TIMEOUT_CMD=$(command -v gtimeout || command -v timeout || echo "")
    if [[ -n "$TIMEOUT_CMD" ]]; then
-        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int' || test $? -eq 137
+        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=int-postgres -m "not semantic and not benchmark" test-int' || test $? -eq 137
    else
        echo "⚠️  No timeout command found, running without timeout..."
-        BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int
+        BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=int-postgres -m "not semantic and not benchmark" test-int
    fi

 # Run tests impacted by recent changes (requires pytest-testmon)
 # Pass paths or node ids after `just testmon` to limit the candidate set further.
-testmon *args:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov --testmon {{args}}
+testmon *args: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_SELECT_FLAGS}} --testmon-env=local {{args}}
+
+# Seed pytest-testmon data into this worktree from the shared Git cache.
+testmon-seed:
+    uv run python scripts/testmon_cache.py seed
+
+# Refresh the shared pytest-testmon cache from a full backend test run.
+testmon-refresh:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    BASIC_MEMORY_TESTMON_FLAGS="{{TESTMON_REFRESH_FLAGS}}" just test
+    uv run python scripts/testmon_cache.py refresh
+
+# Show local and shared pytest-testmon cache locations.
+testmon-status:
+    uv run python scripts/testmon_cache.py status

 # Run MCP smoke test (fast end-to-end loop)
-test-smoke:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m smoke test-int/mcp/test_smoke_integration.py
+test-smoke: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=smoke -m smoke test-int/mcp/test_smoke_integration.py

 # Fast local loop: lint, format, typecheck, impacted tests via pytest-testmon
 fast-check:
@@ -97,18 +117,18 @@ postgres-migrate:
 # Run Windows-specific tests only (only works on Windows platform)
 # These tests verify Windows-specific database optimizations (locking mode, NullPool)
 # Will be skipped automatically on non-Windows platforms
-test-windows:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m windows tests test-int
+test-windows: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=windows -m windows tests test-int

 # Run benchmark tests only (performance testing)
 # These are slow tests that measure sync performance with various file counts
 # Excluded from default test runs to keep CI fast
-test-benchmark:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m benchmark tests test-int
+test-benchmark: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=benchmark -m benchmark tests test-int

 # Run semantic search quality benchmarks (all combos)
-test-semantic:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m semantic test-int/semantic/
+test-semantic: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=semantic -m semantic test-int/semantic/

 # Run semantic benchmarks with JSON artifact output, then show report
 test-semantic-report:
@@ -120,8 +140,8 @@ test-litellm-live *args:
    BASIC_MEMORY_ENV=test BASIC_MEMORY_RUN_LITELLM_INTEGRATION=1 PYTHONPATH=test-int:src uv run python -m semantic.litellm_live_harness {{args}}

 # Run semantic benchmarks (Postgres combos only)
-test-semantic-postgres:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m semantic -k postgres test-int/semantic/
+test-semantic-postgres: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=semantic-postgres -m semantic -k postgres test-int/semantic/

 # View semantic benchmark results (rich formatted table)
 # Usage: just semantic-report [--filter-combo sqlite] [--filter-suite paraphrase] [--sort-by avg_latency_ms]
@@ -137,8 +157,8 @@ benchmark-compare baseline candidate *args:

 # Run all tests including Windows, Postgres, and Benchmarks (for CI/comprehensive testing)
 # Use this before releasing to ensure everything works across all backends and platforms
-test-all:
-    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov tests test-int
+test-all: testmon-seed
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov {{TESTMON_FLAGS}} --testmon-env=all tests test-int

 # Generate HTML coverage report
 coverage:
@@ -24,7 +24,7 @@ Memory's durable graph**, rather than a memory layer of its own. See
  configures the project for the plugin: maps it to a Basic Memory project (picking
  an existing one or creating a new one), seeds the `session`/`decision`/`task`
  schemas into the project, installs the shared `memory-*` skills via
-  `npx skills add basicmachines-co/basic-memory --path skills` (the plugin doesn't
+  `npx skills add basicmachines-co/basic-memory/skills` (the plugin doesn't
  vendor its own copies — `skills/` is the single source of truth, shared with
  OpenClaw), optionally learns the project's placement conventions, and enables the
  capture reflexes. Writes the `basicMemory` block to
@@ -156,7 +156,7 @@ git ls-files skills/ | grep -q memory- && echo "source repo - skip install"
 Otherwise, run from the project root:

 ```
-npx skills add basicmachines-co/basic-memory --path skills
+npx skills add basicmachines-co/basic-memory/skills
 ```

 This installs the canonical `memory-*` skills into the user's skills directory — the
@@ -76,6 +76,10 @@ addopts = "--cov=basic_memory --cov-report term-missing"
 testpaths = ["tests", "test-int"]
 asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
+# Any test hanging >120s fails with a stack dump instead of stalling the CI job
+# until the runner times out (the FastMCP/asyncpg cleanup-hang family).
+timeout = 120
+timeout_method = "thread"
 filterwarnings = [
    "ignore:The @wait_container_is_ready decorator is deprecated.*:DeprecationWarning:testcontainers\\.core\\.waiting_utils",
    "ignore:The default datetime adapter is deprecated as of Python 3\\.12.*:DeprecationWarning:aiosqlite\\.core",
@@ -115,6 +119,7 @@ dev = [
    "ty>=0.0.18",
    "cst-lsp>=0.1.3",
    "libcst>=1.8.6",
+    "pytest-timeout>=2.4.0",
 ]

 [tool.hatch.version]
@@ -0,0 +1,534 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#   "typer>=0.9.0",
+# ]
+# ///
+"""BM Bossbot status and PR-body helpers.
+
+BM Bossbot is a deterministic merge gate — no LLM review. It approves a head
+SHA only when the Tests workflow succeeded for it (enforced by the workflow
+trigger), the PR is not a draft, the author is trusted, and every review
+thread is resolved. Code review itself comes from the Codex connector and
+human reviewers; this gate just refuses to let unaddressed feedback merge.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any, Mapping
+
+import typer
+
+
+STATUS_CONTEXT = "BM Bossbot Approval"
+SUMMARY_START = "<!-- BM_BOSSBOT_SUMMARY:start -->"
+SUMMARY_END = "<!-- BM_BOSSBOT_SUMMARY:end -->"
+APPROVED_DESCRIPTION = "BM Bossbot approved this head SHA"
+PENDING_DESCRIPTION = "BM Bossbot is reviewing this head SHA"
+app = typer.Typer(
+    add_completion=False,
+    help="Manage deterministic BM Bossbot PR approval statuses.",
+    no_args_is_help=True,
+)
+
+
+@dataclass(frozen=True)
+class ApprovalResult:
+    approved: bool
+    state: str
+    description: str
+
+
+@dataclass(frozen=True)
+class PullRequestEvent:
+    repo: str
+    number: int
+    head_sha: str
+    body: str
+
+
+def read_json(path: Path) -> Any:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise SystemExit(f"Missing JSON file: {path}") from None
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"{path}: invalid JSON: {exc}") from None
+
+
+def pull_request_event(
+    payload: Mapping[str, Any], repo_override: str | None = None
+) -> PullRequestEvent:
+    pr = payload.get("pull_request")
+    if not isinstance(pr, Mapping):
+        raise SystemExit("GitHub event payload is missing pull_request")
+
+    repo = repo_override
+    if repo is None:
+        repository = payload.get("repository")
+        if isinstance(repository, Mapping):
+            repo = _string(repository.get("full_name"))
+    if not repo:
+        raise SystemExit("Could not determine GitHub repository")
+
+    number = pr.get("number")
+    if not isinstance(number, int):
+        raise SystemExit("GitHub event payload is missing pull_request.number")
+
+    head = pr.get("head")
+    head_sha = (
+        _string(head.get("sha")) if isinstance(head, Mapping) else _string(pr.get("head_sha"))
+    )
+    if not head_sha:
+        raise SystemExit("GitHub event payload is missing pull_request.head.sha")
+
+    return PullRequestEvent(
+        repo=repo,
+        number=number,
+        head_sha=head_sha,
+        body=_string(pr.get("body")),
+    )
+
+
+def count_unresolved_review_threads(*, token: str, repo: str, number: int) -> int:
+    """Count unresolved review threads (e.g. open Codex inline comments) on a PR.
+
+    Review threads are the canonical 'outstanding feedback' signal: bot reviewers
+    submit COMMENTED reviews that never flip reviewDecision, so thread resolution
+    is the only deterministic way to know feedback was addressed.
+    """
+    owner, _, name = repo.partition("/")
+    if not owner or not name:
+        raise SystemExit(f"Invalid repository: {repo}")
+
+    query = """
+    query($owner: String!, $name: String!, $number: Int!, $cursor: String) {
+      repository(owner: $owner, name: $name) {
+        pullRequest(number: $number) {
+          reviewThreads(first: 100, after: $cursor) {
+            pageInfo { hasNextPage endCursor }
+            nodes { isResolved }
+          }
+        }
+      }
+    }
+    """
+
+    unresolved = 0
+    cursor: str | None = None
+    while True:
+        response = _github_request(
+            method="POST",
+            path="/graphql",
+            token=token,
+            payload={
+                "query": query,
+                "variables": {"owner": owner, "name": name, "number": number, "cursor": cursor},
+            },
+        )
+        if not isinstance(response, Mapping) or response.get("errors"):
+            raise SystemExit(f"GitHub GraphQL reviewThreads query failed: {response}")
+        try:
+            threads = response["data"]["repository"]["pullRequest"]["reviewThreads"]
+            nodes = threads["nodes"]
+            page_info = threads["pageInfo"]
+        except (KeyError, TypeError):
+            raise SystemExit(
+                "GitHub GraphQL reviewThreads response was missing expected fields"
+            ) from None
+        unresolved += sum(1 for node in nodes if not node.get("isResolved"))
+        if not page_info.get("hasNextPage"):
+            return unresolved
+        cursor = page_info.get("endCursor")
+
+
+def unresolved_threads_result(count: int) -> ApprovalResult:
+    return ApprovalResult(
+        False,
+        "failure",
+        f"BM Bossbot found {count} unresolved review thread(s)",
+    )
+
+
+def evaluate_gate(
+    *,
+    token: str,
+    repo: str,
+    number: int,
+    trusted: bool,
+) -> tuple[ApprovalResult, int]:
+    """Deterministic approval decision: trusted author + zero unresolved threads.
+
+    Tests-passed-for-this-head and non-draft are enforced upstream by the
+    workflow trigger and the normalize step (should_review). Returns the
+    result plus the unresolved-thread count for the PR-body summary.
+    """
+    if not trusted:
+        return (
+            ApprovalResult(
+                False,
+                "failure",
+                "BM Bossbot only gates owner/member/collaborator PRs",
+            ),
+            0,
+        )
+    unresolved = count_unresolved_review_threads(token=token, repo=repo, number=number)
+    if unresolved > 0:
+        return unresolved_threads_result(unresolved), unresolved
+    return ApprovalResult(True, "success", APPROVED_DESCRIPTION), 0
+
+
+def build_status_payload(*, state: str, description: str, target_url: str) -> dict[str, str]:
+    return {
+        "state": state,
+        "context": STATUS_CONTEXT,
+        "description": description,
+        "target_url": target_url,
+    }
+
+
+def render_summary(
+    *,
+    head_sha: str,
+    result: ApprovalResult,
+    trusted: bool,
+    unresolved_threads: int,
+) -> str:
+    return "\n".join(
+        [
+            f"Reviewed SHA: `{head_sha}`",
+            "Gate: deterministic (tests, draft, author trust, review threads)",
+            f"Status: `{result.state}` - {result.description}",
+            "",
+            f"- Trusted author: {'yes' if trusted else 'no'}",
+            f"- Unresolved review threads: {unresolved_threads}",
+            "",
+            "Code review comes from the Codex connector and human reviewers;",
+            "resolve every review thread to (re)gain approval for this head SHA.",
+        ]
+    )
+
+
+def upsert_summary_block(body: str, summary: str) -> str:
+    block = f"{SUMMARY_START}\n{summary.rstrip()}\n{SUMMARY_END}"
+    pattern = re.compile(
+        rf"{re.escape(SUMMARY_START)}.*?{re.escape(SUMMARY_END)}",
+        flags=re.DOTALL,
+    )
+    if pattern.search(body):
+        return pattern.sub(block, body, count=1)
+    if body.strip():
+        return f"{body.rstrip()}\n\n{block}\n"
+    return f"{block}\n"
+
+
+def set_commit_status(*, token: str, repo: str, sha: str, payload: Mapping[str, str]) -> None:
+    _github_request(
+        method="POST",
+        path=f"/repos/{repo}/statuses/{sha}",
+        token=token,
+        payload=payload,
+    )
+
+
+def update_pull_request_body(*, token: str, repo: str, number: int, body: str) -> None:
+    _github_request(
+        method="PATCH",
+        path=f"/repos/{repo}/pulls/{number}",
+        token=token,
+        payload={"body": body},
+    )
+
+
+def get_pull_request_body(*, token: str, repo: str, number: int) -> str:
+    response = _github_request(
+        method="GET",
+        path=f"/repos/{repo}/pulls/{number}",
+        token=token,
+    )
+    if not isinstance(response, Mapping):
+        raise SystemExit("GitHub API response for pull request was invalid")
+    return _string(response.get("body"))
+
+
+def mark_pending(
+    *,
+    event_path: Path,
+    repo: str | None,
+    run_url: str,
+    token_env: str,
+) -> None:
+    event = pull_request_event(read_json(event_path), repo_override=repo)
+    set_commit_status(
+        token=_token(token_env),
+        repo=event.repo,
+        sha=event.head_sha,
+        payload=build_status_payload(
+            state="pending",
+            description=PENDING_DESCRIPTION,
+            target_url=run_url,
+        ),
+    )
+    typer.echo(f"Marked {STATUS_CONTEXT} pending for {event.head_sha}")
+
+
+def finalize_review(
+    *,
+    event_path: Path,
+    trusted: bool,
+    repo: str | None,
+    run_url: str,
+    token_env: str,
+) -> ApprovalResult:
+    event = pull_request_event(read_json(event_path), repo_override=repo)
+    token = _token(token_env)
+
+    result, unresolved = evaluate_gate(
+        token=token, repo=event.repo, number=event.number, trusted=trusted
+    )
+    current_body = get_pull_request_body(token=token, repo=event.repo, number=event.number)
+    updated_body = upsert_summary_block(
+        current_body,
+        render_summary(
+            head_sha=event.head_sha,
+            result=result,
+            trusted=trusted,
+            unresolved_threads=unresolved,
+        ),
+    )
+    update_pull_request_body(token=token, repo=event.repo, number=event.number, body=updated_body)
+    set_commit_status(
+        token=token,
+        repo=event.repo,
+        sha=event.head_sha,
+        payload=build_status_payload(
+            state=result.state,
+            description=result.description,
+            target_url=run_url,
+        ),
+    )
+    typer.echo(f"Marked {STATUS_CONTEXT} {result.state} for {event.head_sha}")
+    return result
+
+
+def get_pull_request_head_sha(*, token: str, repo: str, number: int) -> str:
+    response = _github_request(
+        method="GET",
+        path=f"/repos/{repo}/pulls/{number}",
+        token=token,
+    )
+    if not isinstance(response, Mapping):
+        raise SystemExit("GitHub API response for pull request was invalid")
+    head = response.get("head")
+    head_sha = _string(head.get("sha")) if isinstance(head, Mapping) else ""
+    if not head_sha:
+        raise SystemExit("GitHub API response was missing pull request head SHA")
+    return head_sha
+
+
+def head_sha_was_approved(*, token: str, repo: str, sha: str) -> bool:
+    """Return whether a full BM Bossbot review previously approved this head SHA.
+
+    Commit statuses are append-only history, so the approval record survives a
+    later thread-failure status for the same SHA. The recheck path can post a
+    new status on every review-thread event, so a busy PR can accumulate more
+    than one page of statuses — page through all of them or the approval
+    record falls off page one and a valid approval is never restored.
+    """
+    page = 1
+    while True:
+        response = _github_request(
+            method="GET",
+            path=f"/repos/{repo}/commits/{sha}/statuses?per_page=100&page={page}",
+            token=token,
+        )
+        if not isinstance(response, list):
+            raise SystemExit("GitHub API response for commit statuses was invalid")
+        if not response:
+            return False
+        if any(
+            isinstance(status, Mapping)
+            and status.get("context") == STATUS_CONTEXT
+            and status.get("state") == "success"
+            and status.get("description") == APPROVED_DESCRIPTION
+            for status in response
+        ):
+            return True
+        page += 1
+
+
+def recheck_threads(
+    *,
+    repo: str,
+    number: int,
+    run_url: str,
+    token_env: str,
+) -> None:
+    """Re-evaluate the approval status when review threads change.
+
+    Trigger: pull_request_review / review_comment / review_thread events.
+    Why: the full review runs once per head SHA after Tests; feedback that
+         arrives later (or gets resolved later) must move the gate without
+         re-running the LLM review.
+    Outcome: unresolved threads flip the status to failure; once every thread
+         is resolved, a previously earned approval for the same head SHA is
+         restored. Without a prior approval the status is left untouched so a
+         pending/failed review cannot be upgraded by thread resolution alone.
+    """
+    token = _token(token_env)
+    head_sha = get_pull_request_head_sha(token=token, repo=repo, number=number)
+    unresolved = count_unresolved_review_threads(token=token, repo=repo, number=number)
+
+    if unresolved > 0:
+        result = unresolved_threads_result(unresolved)
+    elif head_sha_was_approved(token=token, repo=repo, sha=head_sha):
+        result = ApprovalResult(True, "success", APPROVED_DESCRIPTION)
+    else:
+        typer.echo(
+            f"All review threads resolved but no prior approval exists for {head_sha}; "
+            "leaving status unchanged"
+        )
+        return
+
+    set_commit_status(
+        token=token,
+        repo=repo,
+        sha=head_sha,
+        payload=build_status_payload(
+            state=result.state,
+            description=result.description,
+            target_url=run_url,
+        ),
+    )
+    typer.echo(f"Marked {STATUS_CONTEXT} {result.state} for {head_sha} ({result.description})")
+
+
+def _github_request(
+    *,
+    method: str,
+    path: str,
+    token: str,
+    payload: Mapping[str, Any] | None = None,
+) -> Any:
+    data = None if payload is None else json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        f"https://api.github.com{path}",
+        data=data,
+        method=method,
+        headers={
+            "Accept": "application/vnd.github+json",
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "User-Agent": "basic-memory-bm-bossbot",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            response_body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise SystemExit(f"GitHub API request failed: {exc.code} {detail}") from None
+    return json.loads(response_body) if response_body else None
+
+
+def _string(value: object) -> str:
+    return value if isinstance(value, str) else ""
+
+
+def _token(env_name: str) -> str:
+    token = os.environ.get(env_name)
+    if not token:
+        raise SystemExit(f"Missing required token environment variable: {env_name}")
+    return token
+
+
+@app.command("pending")
+def pending(
+    event: Annotated[
+        Path,
+        typer.Option(
+            "--event",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help="GitHub event payload JSON.",
+        ),
+    ],
+    run_url: Annotated[str, typer.Option("--run-url", help="Workflow run URL.")],
+    repo: Annotated[str | None, typer.Option("--repo", help="owner/name repository.")] = None,
+    token_env: Annotated[
+        str,
+        typer.Option("--token-env", help="Environment variable containing a GitHub token."),
+    ] = "GITHUB_TOKEN",
+) -> None:
+    """Set BM Bossbot Approval pending on the PR head SHA."""
+    mark_pending(event_path=event, repo=repo, run_url=run_url, token_env=token_env)
+
+
+@app.command("finalize")
+def finalize(
+    event: Annotated[
+        Path,
+        typer.Option(
+            "--event",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help="GitHub event payload JSON.",
+        ),
+    ],
+    trusted: Annotated[
+        str,
+        typer.Option(
+            "--trusted",
+            help="Whether the PR author is trusted (true/false from the classify step).",
+        ),
+    ],
+    run_url: Annotated[str, typer.Option("--run-url", help="Workflow run URL.")],
+    repo: Annotated[str | None, typer.Option("--repo", help="owner/name repository.")] = None,
+    token_env: Annotated[
+        str,
+        typer.Option("--token-env", help="Environment variable containing a GitHub token."),
+    ] = "GITHUB_TOKEN",
+) -> None:
+    """Finalize BM Bossbot Approval from the deterministic gate."""
+    result = finalize_review(
+        event_path=event,
+        trusted=trusted.strip().lower() == "true",
+        repo=repo,
+        run_url=run_url,
+        token_env=token_env,
+    )
+    if not result.approved:
+        raise typer.Exit(1)
+
+
+@app.command("recheck")
+def recheck(
+    pr_number: Annotated[int, typer.Option("--pr-number", min=1, help="Pull request number.")],
+    run_url: Annotated[str, typer.Option("--run-url", help="Workflow run URL.")],
+    repo: Annotated[str, typer.Option("--repo", help="owner/name repository.")],
+    token_env: Annotated[
+        str,
+        typer.Option("--token-env", help="Environment variable containing a GitHub token."),
+    ] = "GITHUB_TOKEN",
+) -> None:
+    """Re-evaluate BM Bossbot Approval from current review-thread state."""
+    recheck_threads(repo=repo, number=pr_number, run_url=run_url, token_env=token_env)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,166 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#   "openai>=1.100.2",
+#   "python-dotenv>=1.1.0",
+#   "typer>=0.9.0",
+# ]
+# ///
+"""Generate a BM Bossbot infographic with the OpenAI Images API."""
+
+from __future__ import annotations
+
+import base64
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from dotenv import load_dotenv
+from openai import OpenAI
+
+
+DEFAULT_MODEL = "gpt-image-2"
+DEFAULT_SIZE = "1536x1024"
+DEFAULT_QUALITY = "high"
+DEFAULT_FORMAT = "webp"
+DEFAULT_COMPRESSION = 90
+app = typer.Typer(
+    add_completion=False,
+    help="Generate Basic Memory infographics with the OpenAI Images API.",
+    no_args_is_help=True,
+)
+
+
+@dataclass(frozen=True)
+class GeneratedImage:
+    path: Path
+    revised_prompt: str | None
+
+
+def validate_output_path(path: Path, *, repo_root: Path | None = None) -> Path:
+    root = (repo_root or Path.cwd()).resolve()
+    output = path.resolve()
+    allowed_root = (root / "docs" / "assets" / "infographics").resolve()
+    if not output.is_relative_to(allowed_root):
+        allowed_path = allowed_root.relative_to(root).as_posix()
+        raise ValueError(f"Output path must be under {allowed_path}")
+    if output.suffix != ".webp":
+        raise ValueError("Output path must end with .webp")
+    return output
+
+
+def generate_image_result(
+    *,
+    prompt: str,
+    output_path: Path,
+    model: str = DEFAULT_MODEL,
+    size: str = DEFAULT_SIZE,
+    quality: str = DEFAULT_QUALITY,
+    output_format: str = DEFAULT_FORMAT,
+    output_compression: int = DEFAULT_COMPRESSION,
+    client: Any | None = None,
+    retries: int = 2,
+) -> GeneratedImage:
+    output = validate_output_path(output_path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    load_dotenv()
+    openai_client = client or OpenAI()
+
+    for attempt in range(retries + 1):
+        try:
+            response = openai_client.images.generate(
+                model=model,
+                prompt=prompt,
+                size=size,
+                quality=quality,
+                output_format=output_format,
+                output_compression=output_compression,
+            )
+            image = response.data[0]
+            image_b64 = image.b64_json
+            if not image_b64:
+                raise RuntimeError("OpenAI image response did not include b64_json")
+            output.write_bytes(base64.b64decode(image_b64))
+            return GeneratedImage(path=output, revised_prompt=image.revised_prompt)
+        except Exception:
+            if attempt >= retries:
+                raise
+            time.sleep(2**attempt)
+
+    raise RuntimeError("Image generation retry loop exited unexpectedly")
+
+
+def generate_image(
+    *,
+    prompt: str,
+    output_path: Path,
+    model: str = DEFAULT_MODEL,
+    size: str = DEFAULT_SIZE,
+    quality: str = DEFAULT_QUALITY,
+    output_format: str = DEFAULT_FORMAT,
+    output_compression: int = DEFAULT_COMPRESSION,
+    client: Any | None = None,
+    retries: int = 2,
+) -> Path:
+    return generate_image_result(
+        prompt=prompt,
+        output_path=output_path,
+        model=model,
+        size=size,
+        quality=quality,
+        output_format=output_format,
+        output_compression=output_compression,
+        client=client,
+        retries=retries,
+    ).path
+
+
+@app.command()
+def generate(
+    prompt_file: Annotated[
+        Path,
+        typer.Option(
+            "--prompt-file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help="Markdown/text prompt file to send to the image model.",
+        ),
+    ],
+    output: Annotated[Path, typer.Option("--output", help="Output .webp path.")],
+    model: Annotated[str, typer.Option("--model", help="OpenAI image model.")] = DEFAULT_MODEL,
+    size: Annotated[str, typer.Option("--size", help="Image size.")] = DEFAULT_SIZE,
+    quality: Annotated[str, typer.Option("--quality", help="Image quality.")] = DEFAULT_QUALITY,
+    output_compression: Annotated[
+        int,
+        typer.Option(
+            "--output-compression",
+            min=0,
+            max=100,
+            help="WebP output compression.",
+        ),
+    ] = DEFAULT_COMPRESSION,
+    retries: Annotated[int, typer.Option("--retries", min=0, help="Retry attempts.")] = 2,
+) -> None:
+    """Generate an infographic from a prompt file."""
+    output = generate_image(
+        prompt=prompt_file.read_text(encoding="utf-8"),
+        output_path=output,
+        model=model,
+        size=size,
+        quality=quality,
+        output_compression=output_compression,
+        retries=retries,
+    )
+    typer.echo(output)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,438 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#   "openai>=1.100.2",
+#   "python-dotenv>=1.1.0",
+#   "typer>=0.9.0",
+# ]
+# ///
+"""Build and generate a non-gating BM Bossbot PR image."""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated, Any, Mapping
+
+import typer
+
+if __package__:
+    from .generate_infographic import (
+        DEFAULT_MODEL,
+        DEFAULT_QUALITY,
+        DEFAULT_SIZE,
+        generate_image_result,
+    )
+else:
+    from generate_infographic import (
+        DEFAULT_MODEL,
+        DEFAULT_QUALITY,
+        DEFAULT_SIZE,
+        generate_image_result,
+    )
+
+
+SUMMARY_START = "<!-- BM_BOSSBOT_SUMMARY:start -->"
+SUMMARY_END = "<!-- BM_BOSSBOT_SUMMARY:end -->"
+THEME_START = "<!-- BM_INFOGRAPHIC_THEME:start -->"
+THEME_END = "<!-- BM_INFOGRAPHIC_THEME:end -->"
+PROVENANCE_START = "<!-- BM_INFOGRAPHIC_PROVENANCE:start -->"
+PROVENANCE_END = "<!-- BM_INFOGRAPHIC_PROVENANCE:end -->"
+IMAGE_START = "<!-- pr-infographic:start -->"
+IMAGE_END = "<!-- pr-infographic:end -->"
+# Managed blocks are bot-written artifacts (review verdict, image embed,
+# provenance). They must never feed the image: sourcing the review summary is
+# what made every image an "APPROVED" stamp instead of depicting the change.
+MANAGED_BLOCKS = (
+    (SUMMARY_START, SUMMARY_END),
+    (THEME_START, THEME_END),
+    (PROVENANCE_START, PROVENANCE_END),
+    (IMAGE_START, IMAGE_END),
+)
+app = typer.Typer(
+    add_completion=False,
+    help="Generate a non-gating BM Bossbot PR image.",
+    no_args_is_help=True,
+)
+
+
+class ThemeSource(StrEnum):
+    AUTO = "auto"
+    CLI = "cli"
+    PR_BODY = "pr-body"
+
+
+@dataclass(frozen=True)
+class ThemeSelection:
+    theme: str
+    source: ThemeSource
+
+
+BM_IMAGE_THEME_POOL = (
+    "computer science college textbook: SICP-style diagrams, automata, compiler "
+    "pipelines, type theory, and annotated chalkboard rigor",
+    "classic literature: sea voyages, gothic manors, Dickensian streets, library "
+    "marginalia, and travel-journal artifacts",
+    "fantasy quest ledger: original guild maps, spellbooks, dungeon keys, tavern "
+    "notices, and artifact inventories with no copyrighted settings",
+    "heavy music editorial: metal, hard rock, punk, techno, soul, or reggae "
+    "tour-poster energy with no direct band logos or likenesses",
+    "knockoff space opera: fleet routes, mission consoles, contraband manifests, "
+    "and practical starship drama with no named fictional universes",
+    "sword-and-sorcery: ruined temples, desert roads, battle standards, ancient "
+    "maps, and heroic silhouettes with no named character likenesses",
+    "comic book cover: original splash-page composition, caption boxes, clean "
+    "halftone texture, and bold issue-cover drama",
+    "French new wave movie poster: stark typography, city streets, jump-cut "
+    "composition, and high-contrast editorial photography cues",
+    "WWII public-information poster: home-front logistics, mobilization arrows, "
+    "bold simplified figures, and no real-world party symbols or hate imagery",
+    "Italian movie poster: hand-painted drama, expressive color, credit-block "
+    "energy, and 1960s or 1970s cinema composition with no actor likenesses",
+    "Shakespearean stage: acts and scenes, court intrigue, stage blocking, "
+    "dramatis personae, backstage cue sheets, and theatrical light",
+    "Greek mythology: temple steps, oracle tablets, constellations, labyrinths, "
+    "ship routes, and original heroic allegory",
+    "noir detective photography: case files, typed evidence labels, civic "
+    "infrastructure, streetlight shadows, and newsroom archive grit",
+    "space exploration and astronomy: celestial atlases, observatory charts, "
+    "orbital mechanics, planetary survey routes, and deep-space mission drama",
+    "editorial painting: abstract, classical landscape, western action, "
+    "chiaroscuro, historical mural, stormy seascape, or allegorical canvas",
+    "classic black-and-white photography: documentary field report, contact "
+    "sheet, street photography, civic infrastructure, and darkroom contrast",
+    "80's action movie poster: smoky backlit warehouses, neon streets, practical "
+    "explosions, mission dossiers, countdowns, and no actor likenesses",
+    "alchemy manuscript: transformation diagrams, annotated symbols, recipe-like "
+    "process artifacts, and illuminated margins",
+    "brutalist civic planning: concrete signage, zoning blocks, transit diagrams, "
+    "infrastructure maps, and stern public-service clarity",
+)
+
+
+def build_change_shape(
+    context: Mapping[str, Any],
+    *,
+    max_commits: int = 10,
+    max_files: int = 10,
+) -> str:
+    """Render a compact factual digest of the PR: labels, linked issues, commits, files.
+
+    Mirrors the delivery context the Basic Memory CI capture flow collects
+    (ProjectUpdateContext): the goal is to ground the image in the theme of the
+    WHOLE change — what it touches and why — not just the title/description.
+    """
+    lines: list[str] = []
+
+    labels = [str(label.get("name", "")) for label in context.get("labels") or []]
+    labels = [label for label in labels if label]
+    if labels:
+        lines.append(f"Labels: {', '.join(labels)}")
+
+    issues = context.get("closingIssuesReferences") or []
+    if issues:
+        lines.append("Linked issues:")
+        for issue in issues:
+            number = issue.get("number")
+            title = str(issue.get("title") or "").strip()
+            lines.append(f"- #{number}: {title}" if title else f"- #{number}")
+
+    commits = context.get("commits") or []
+    subjects = [str(commit.get("messageHeadline") or "").strip() for commit in commits]
+    # Merge commits carry no thematic signal — they're branch bookkeeping.
+    subjects = [
+        subject
+        for subject in subjects
+        if subject and not subject.startswith(("Merge branch ", "Merge pull request "))
+    ]
+    if subjects:
+        lines.append(f"Commit subjects ({len(subjects)} total):")
+        lines.extend(f"- {subject}" for subject in subjects[:max_commits])
+        if len(subjects) > max_commits:
+            lines.append(f"- ... and {len(subjects) - max_commits} more")
+
+    files = context.get("files") or []
+    if files:
+        additions = sum(int(item.get("additions") or 0) for item in files)
+        deletions = sum(int(item.get("deletions") or 0) for item in files)
+        lines.append(f"Files changed ({len(files)} total, +{additions}/-{deletions}):")
+        ranked = sorted(
+            files,
+            key=lambda item: int(item.get("additions") or 0) + int(item.get("deletions") or 0),
+            reverse=True,
+        )
+        for item in ranked[:max_files]:
+            path = str(item.get("path") or "")
+            lines.append(f"- {path} (+{item.get('additions') or 0}/-{item.get('deletions') or 0})")
+        if len(files) > max_files:
+            lines.append(f"- ... and {len(files) - max_files} more files")
+
+    return "\n".join(lines) if lines else "(no additional change context available)"
+
+
+def extract_pr_content(pr_body: str) -> str:
+    """Return the author's own PR description with all managed bot blocks removed."""
+    content = pr_body
+    for start, end in MANAGED_BLOCKS:
+        content = re.sub(
+            rf"{re.escape(start)}.*?{re.escape(end)}",
+            "",
+            content,
+            flags=re.DOTALL,
+        )
+    return content.strip()
+
+
+def extract_infographic_theme(pr_body: str) -> str | None:
+    pattern = re.compile(
+        rf"{re.escape(THEME_START)}\s*(.*?)\s*{re.escape(THEME_END)}",
+        flags=re.DOTALL,
+    )
+    match = pattern.search(pr_body)
+    if not match:
+        return None
+    theme = match.group(1).strip()
+    return theme or None
+
+
+def select_image_theme(
+    *,
+    pr_number: int,
+    pr_title: str,
+    pr_body: str,
+    theme_override: str | None,
+) -> ThemeSelection:
+    if theme_override:
+        return ThemeSelection(theme=theme_override, source=ThemeSource.CLI)
+    body_theme = extract_infographic_theme(pr_body)
+    if body_theme:
+        return ThemeSelection(theme=body_theme, source=ThemeSource.PR_BODY)
+    # Seed on author-owned PR identity, not the review summary, so the pick is
+    # stable across re-reviews of the same PR.
+    seed = f"{pr_number}\n{pr_title}".encode("utf-8")
+    index = int.from_bytes(hashlib.sha256(seed).digest()[:2], byteorder="big") % len(
+        BM_IMAGE_THEME_POOL
+    )
+    return ThemeSelection(theme=BM_IMAGE_THEME_POOL[index], source=ThemeSource.AUTO)
+
+
+def _preformatted(value: str) -> str:
+    return f"<pre><code>{html.escape(value, quote=False)}</code></pre>"
+
+
+def build_infographic_provenance_block(
+    *,
+    pr_number: int,
+    output_path: Path,
+    model: str,
+    size: str,
+    quality: str,
+    theme: str,
+    theme_source: ThemeSource,
+) -> str:
+    return f"""
+{PROVENANCE_START}
+<details>
+<summary>BM Bossbot image choices</summary>
+
+- Pull request: `#{pr_number}`
+- Generated asset: `{output_path.as_posix()}`
+- Image model: `{model}`
+- Size: `{size}`
+- Quality: `{quality}`
+- Image mode: `editorial-image`
+- Theme source: `{theme_source.value}`
+
+Theme / visual direction:
+{_preformatted(theme)}
+
+</details>
+{PROVENANCE_END}
+""".strip()
+
+
+def upsert_managed_block(body: str, *, block: str, start: str, end: str) -> str:
+    pattern = re.compile(rf"{re.escape(start)}.*?{re.escape(end)}", flags=re.DOTALL)
+    if pattern.search(body):
+        return pattern.sub(block, body, count=1)
+    if body.strip():
+        return f"{body.rstrip()}\n\n{block}\n"
+    return f"{block}\n"
+
+
+def build_infographic_prompt(
+    *,
+    pr_number: int,
+    pr_title: str,
+    pr_content: str,
+    change_shape: str,
+    theme: str,
+    theme_source: ThemeSource,
+) -> str:
+    theme_label = (
+        "Selected BM visual direction"
+        if theme_source == ThemeSource.AUTO
+        else "User-supplied visual direction"
+    )
+
+    return f"""
+Create a polished landscape WebP editorial image for Basic Memory PR #{pr_number}.
+
+Your subject is the CONTENT of the pull request — what the change does and why
+it matters — described in the title, description, and change shape below.
+Express the theme of the whole change as a visual story.
+
+This image is decoration for the PR conversation. It is NOT a review artifact:
+do not depict review verdicts, approval, or process. Never render approval
+stamps, "APPROVED"/"SUCCESS"/"VERDICT" wording, rubber stamps, wax seals of
+approval, badges, checkmarks, checklists, status lines, SHA strings, or
+BM Bossbot itself. If the composition needs text, draw it from the change's
+subject matter only.
+
+Pull request title:
+{pr_title}
+
+Pull request description:
+{pr_content}
+
+Change shape — factual delivery context (labels, linked issues, commit
+subjects, changed files). Use it to understand what the whole PR touches and
+let that steer the imagery. It is context, NOT captions: never render file
+paths, diff stats, issue numbers, or commit subjects verbatim in the image.
+{change_shape}
+
+{theme_label}:
+{theme}
+
+Treat the visual direction as style inspiration only. Do not let it override
+facts, readability, source material, or the prohibition on review imagery.
+
+Use image-first composition: create a scene, movie poster, editorial painting,
+classic photograph, cover image, symbolic tableau, staged artifact, or another
+visual moment that expresses the PR intent.
+
+Make the selected direction shape the subject, lighting, composition, props,
+environment, and mood. Use one strong focal point. Prefer visual metaphor over
+explanatory UI.
+
+Use at most a short title and zero to three short labels if text helps. Any text
+that appears must be high-contrast, smooth, anti-aliased, and readable.
+
+Do not render an infographic, dashboard, flowchart, timeline strip, checklist,
+bullet-list panel, data panel, or dense explanatory diagram.
+
+Avoid fake screenshots, code blocks, invented claims, copyrighted characters,
+logos, named fictional universes, direct band logos, album art, celebrity
+likenesses, or decorations that obscure content.
+""".strip()
+
+
+@app.command()
+def generate(
+    pr_number: Annotated[
+        int,
+        typer.Option("--pr-number", min=1, help="Pull request number."),
+    ],
+    pr_context_file: Annotated[
+        Path,
+        typer.Option(
+            "--pr-context-file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help=(
+                "JSON from `gh pr view --json "
+                "title,body,labels,files,commits,closingIssuesReferences`."
+            ),
+        ),
+    ],
+    output: Annotated[Path, typer.Option("--output", help="Output .webp path.")],
+    model: Annotated[str, typer.Option("--model", help="OpenAI image model.")] = DEFAULT_MODEL,
+    size: Annotated[str, typer.Option("--size", help="Image size.")] = DEFAULT_SIZE,
+    quality: Annotated[str, typer.Option("--quality", help="Image quality.")] = DEFAULT_QUALITY,
+    retries: Annotated[int, typer.Option("--retries", min=0, help="Retry attempts.")] = 2,
+    theme: Annotated[
+        str | None,
+        typer.Option("--theme", help="Optional visual theme preference."),
+    ] = None,
+    provenance_output: Annotated[
+        Path | None,
+        typer.Option(
+            "--provenance-output",
+            dir_okay=False,
+            help="Optional file to write the managed PR-body provenance block.",
+        ),
+    ] = None,
+    print_prompt: Annotated[
+        bool,
+        typer.Option(
+            "--print-prompt",
+            "--dry-run",
+            help="Print the generated prompt and exit without calling OpenAI. Alias: --dry-run.",
+        ),
+    ] = False,
+) -> None:
+    """Generate the canonical PR image from the PR's title, description, and change shape."""
+    context = json.loads(pr_context_file.read_text(encoding="utf-8"))
+    if not isinstance(context, Mapping):
+        raise typer.BadParameter("PR context file must contain a JSON object")
+    pr_title = str(context.get("title") or "")
+    pr_body = str(context.get("body") or "")
+    pr_content = extract_pr_content(pr_body)
+    change_shape = build_change_shape(context)
+    theme_selection = select_image_theme(
+        pr_number=pr_number,
+        pr_title=pr_title,
+        pr_body=pr_body,
+        theme_override=theme,
+    )
+    prompt = build_infographic_prompt(
+        pr_number=pr_number,
+        pr_title=pr_title,
+        pr_content=pr_content,
+        change_shape=change_shape,
+        theme=theme_selection.theme,
+        theme_source=theme_selection.source,
+    )
+    if print_prompt:
+        typer.echo(prompt)
+        raise typer.Exit()
+
+    image_result = generate_image_result(
+        prompt=prompt,
+        output_path=output,
+        model=model,
+        size=size,
+        quality=quality,
+        retries=retries,
+    )
+    output_path = image_result.path
+    if provenance_output:
+        provenance_output.parent.mkdir(parents=True, exist_ok=True)
+        provenance_output.write_text(
+            build_infographic_provenance_block(
+                pr_number=pr_number,
+                output_path=output_path,
+                model=model,
+                size=size,
+                quality=quality,
+                theme=theme_selection.theme,
+                theme_source=theme_selection.source,
+            ),
+            encoding="utf-8",
+        )
+    typer.echo(output_path)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""Seed and refresh shared pytest-testmon data for Git worktrees."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import NamedTuple
+
+TESTMON_FILENAMES = (".testmondata", ".testmondata-shm", ".testmondata-wal")
+TESTMON_CACHE_ENV = "BM_TESTMON_CACHE_DIR"
+
+
+class TestmonCacheResult(NamedTuple):
+    status: str
+    source_dir: Path
+    destination_dir: Path
+    copied: tuple[Path, ...]
+
+
+def _run_git(args: list[str], cwd: Path) -> str:
+    return subprocess.check_output(["git", *args], cwd=cwd, text=True).strip()
+
+
+def resolve_repo_root(repo_root: Path | None = None) -> Path:
+    if repo_root is not None:
+        return repo_root.expanduser().resolve()
+
+    return Path(_run_git(["rev-parse", "--show-toplevel"], Path.cwd())).resolve()
+
+
+def resolve_cache_dir(repo_root: Path, cache_dir: Path | None = None) -> Path:
+    if cache_dir is not None:
+        return cache_dir.expanduser().resolve()
+
+    if env_cache_dir := os.environ.get(TESTMON_CACHE_ENV):
+        return Path(env_cache_dir).expanduser().resolve()
+
+    git_common_dir = Path(_run_git(["rev-parse", "--git-common-dir"], repo_root))
+    if not git_common_dir.is_absolute():
+        git_common_dir = repo_root / git_common_dir
+
+    return git_common_dir.resolve() / "testmon-cache" / "main"
+
+
+def _testmon_datafile(directory: Path) -> Path:
+    return directory / ".testmondata"
+
+
+def _testmon_files(directory: Path) -> list[Path]:
+    return [
+        directory / filename for filename in TESTMON_FILENAMES if (directory / filename).is_file()
+    ]
+
+
+def _remove_path(path: Path) -> None:
+    if path.is_dir():
+        shutil.rmtree(path)
+    elif path.exists():
+        path.unlink()
+
+
+def _copy_testmon_files(source_dir: Path, destination_dir: Path) -> tuple[Path, ...]:
+    destination_dir.mkdir(parents=True, exist_ok=True)
+
+    copied: list[Path] = []
+    for source in _testmon_files(source_dir):
+        destination = destination_dir / source.name
+        shutil.copy2(source, destination)
+        copied.append(destination)
+
+    return tuple(copied)
+
+
+def seed_testmon_data(repo_root: Path, cache_dir: Path) -> TestmonCacheResult:
+    local_datafile = _testmon_datafile(repo_root)
+    shared_datafile = _testmon_datafile(cache_dir)
+
+    if local_datafile.exists():
+        return TestmonCacheResult(
+            status="exists",
+            source_dir=cache_dir,
+            destination_dir=repo_root,
+            copied=(),
+        )
+
+    if not shared_datafile.exists():
+        return TestmonCacheResult(
+            status="missing",
+            source_dir=cache_dir,
+            destination_dir=repo_root,
+            copied=(),
+        )
+
+    # A worktree with sidecars but no main database is stale; replace the set
+    # together so SQLite never sees a mixed local/cache snapshot.
+    for filename in TESTMON_FILENAMES:
+        _remove_path(repo_root / filename)
+
+    copied = _copy_testmon_files(cache_dir, repo_root)
+    return TestmonCacheResult(
+        status="seeded",
+        source_dir=cache_dir,
+        destination_dir=repo_root,
+        copied=copied,
+    )
+
+
+def refresh_testmon_data(repo_root: Path, cache_dir: Path) -> TestmonCacheResult:
+    local_datafile = _testmon_datafile(repo_root)
+
+    if not local_datafile.exists():
+        raise FileNotFoundError(
+            f"No local pytest-testmon data at {local_datafile}; run tests first."
+        )
+
+    cache_parent = cache_dir.parent
+    cache_parent.mkdir(parents=True, exist_ok=True)
+    temp_dir = Path(tempfile.mkdtemp(prefix=f".{cache_dir.name}.", dir=cache_parent))
+    backup_dir = cache_parent / f".{cache_dir.name}.previous-{os.getpid()}"
+    copied: tuple[Path, ...] = ()
+
+    try:
+        copied = _copy_testmon_files(repo_root, temp_dir)
+
+        _remove_path(backup_dir)
+        if cache_dir.exists():
+            cache_dir.rename(backup_dir)
+
+        try:
+            temp_dir.rename(cache_dir)
+        except Exception:
+            if backup_dir.exists() and not cache_dir.exists():
+                backup_dir.rename(cache_dir)
+            raise
+    finally:
+        _remove_path(temp_dir)
+        _remove_path(backup_dir)
+
+    return TestmonCacheResult(
+        status="refreshed",
+        source_dir=repo_root,
+        destination_dir=cache_dir,
+        copied=tuple(cache_dir / path.name for path in copied),
+    )
+
+
+def _print_seed_result(result: TestmonCacheResult) -> None:
+    if result.status == "seeded":
+        print(f"Seeded pytest-testmon data from {result.source_dir} into {result.destination_dir}")
+    elif result.status == "exists":
+        print(f"Local pytest-testmon data already exists at {result.destination_dir}")
+    elif result.status == "missing":
+        print(
+            f"No shared pytest-testmon baseline at {result.source_dir}; "
+            "run `just testmon-refresh` after a full backend test run to create one."
+        )
+    else:
+        raise ValueError(f"Unexpected seed result: {result.status}")
+
+
+def _print_refresh_result(result: TestmonCacheResult) -> None:
+    print(f"Published pytest-testmon data from {result.source_dir} to {result.destination_dir}")
+
+
+def _print_status(repo_root: Path, cache_dir: Path) -> None:
+    print(f"Repo root:      {repo_root}")
+    print(f"Worktree data:  {_testmon_datafile(repo_root)}")
+    print(f"Shared cache:   {_testmon_datafile(cache_dir)}")
+    print(f"Worktree ready: {_testmon_datafile(repo_root).exists()}")
+    print(f"Cache ready:    {_testmon_datafile(cache_dir).exists()}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        help="Repository root to operate on (default: git rev-parse --show-toplevel)",
+    )
+    parser.add_argument(
+        "--cache-dir",
+        type=Path,
+        help=(
+            "Shared testmon cache directory "
+            f"(default: ${TESTMON_CACHE_ENV} or <git-common-dir>/testmon-cache/main)"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("seed", help="Copy shared testmon data into this worktree if missing")
+    subparsers.add_parser("refresh", help="Publish this worktree's testmon data to the cache")
+    subparsers.add_parser("status", help="Show local and shared testmon data paths")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    repo_root = resolve_repo_root(args.repo_root)
+    cache_dir = resolve_cache_dir(repo_root, args.cache_dir)
+
+    if args.command == "seed":
+        _print_seed_result(seed_testmon_data(repo_root=repo_root, cache_dir=cache_dir))
+        return 0
+
+    if args.command == "refresh":
+        _print_refresh_result(refresh_testmon_data(repo_root=repo_root, cache_dir=cache_dir))
+        return 0
+
+    if args.command == "status":
+        _print_status(repo_root=repo_root, cache_dir=cache_dir)
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -54,13 +54,13 @@ Users can install or update skills with the [Skills CLI](https://github.com/verc

 ```bash
 # Install all skills
-npx skills add basicmachines-co/basic-memory --path skills
+npx skills add basicmachines-co/basic-memory/skills

 # Install a specific skill
-npx skills add basicmachines-co/basic-memory --path skills --skill memory-tasks
+npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks

 # Install for a specific agent
-npx skills add basicmachines-co/basic-memory --path skills --agent claude
+npx skills add basicmachines-co/basic-memory/skills --agent claude
 ```

 ## Adding a New Skill
@@ -47,16 +47,16 @@ Install or update skills using the [Skills CLI](https://github.com/vercel-labs/s

 ```bash
 # Install all skills
-npx skills add basicmachines-co/basic-memory --path skills
+npx skills add basicmachines-co/basic-memory/skills

 # Install a specific skill
-npx skills add basicmachines-co/basic-memory --path skills --skill memory-tasks
+npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks

 # Install all skills for a specific agent
-npx skills add basicmachines-co/basic-memory --path skills --agent claude
+npx skills add basicmachines-co/basic-memory/skills --agent claude

 # List available skills without installing
-npx skills add basicmachines-co/basic-memory --path skills --list
+npx skills add basicmachines-co/basic-memory/skills --list

 # Check for updates
 npx skills check
@@ -67,7 +67,7 @@ npx skills update

 Skills are installed to your agent's skills directory (e.g., `~/.claude/skills/` for Claude Code global, or `.claude/skills/` for project-scoped).

-If your installed Skills CLI does not support `--path`, copy the `memory-*` directories manually for now. Phase 2 will add a first-class Codex/package install path.
+If your installed Skills CLI cannot load `basicmachines-co/basic-memory/skills`, update the CLI or copy the `memory-*` directories manually.

 ### Claude Desktop (claude.ai)

@@ -32,14 +32,33 @@ def _rclone_exclude_filters(pattern: str) -> list[str]:
    return [f"- {path_pattern}", f"- {path_pattern}/**"]


-async def get_mount_info() -> TenantMountInfo:
-    """Get current tenant information from cloud API."""
+def _workspace_id_header(workspace_id: str | None) -> dict[str, str]:
+    """Header that routes a /tenant/mount/* request to a specific tenant.
+
+    The mount endpoints resolve the workspace from X-Workspace-ID (validating
+    membership + subscription) and fall back to the user's default tenant when
+    it is absent — so omitting it preserves the original default-tenant behavior.
+    """
+    return {"X-Workspace-ID": workspace_id} if workspace_id else {}
+
+
+async def get_mount_info(*, workspace_id: str | None = None) -> TenantMountInfo:
+    """Get tenant mount info (bucket name + tenant id) from the cloud API.
+
+    Args:
+        workspace_id: Tenant id of the target workspace. When omitted, the API
+            uses the authenticated user's default tenant.
+    """
    try:
        config_manager = ConfigManager()
        config = config_manager.config
        host_url = config.cloud_host.rstrip("/")

-        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
+        response = await make_api_request(
+            method="GET",
+            url=f"{host_url}/tenant/mount/info",
+            headers=_workspace_id_header(workspace_id),
+        )

        return TenantMountInfo.model_validate(response.json())
    except Exception as e:
@@ -47,13 +66,24 @@ async def get_mount_info() -> TenantMountInfo:


 async def generate_mount_credentials(tenant_id: str) -> MountCredentials:
-    """Generate scoped credentials for syncing."""
+    """Generate scoped S3 credentials for syncing a specific tenant's bucket.
+
+    Args:
+        tenant_id: Tenant id whose bucket-scoped credentials to mint. Routed via
+            X-Workspace-ID so team workspaces get their own bucket's credentials.
+    """
    try:
        config_manager = ConfigManager()
        config = config_manager.config
        host_url = config.cloud_host.rstrip("/")

-        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
+        # The mount endpoints resolve X-Workspace-ID by matching the workspace's
+        # tenant_id, so passing a tenant_id here is the correct routing key.
+        response = await make_api_request(
+            method="POST",
+            url=f"{host_url}/tenant/mount/credentials",
+            headers=_workspace_id_header(tenant_id),
+        )

        return MountCredentials.model_validate(response.json())
    except Exception as e:
@@ -26,15 +26,52 @@ from basic_memory.cli.commands.cloud.bisync_commands import (
    generate_mount_credentials,
    get_mount_info,
 )
-from basic_memory.cli.commands.cloud.rclone_config import configure_rclone_remote
+from basic_memory.cli.commands.cloud.rclone_config import (
+    configure_rclone_remote,
+    rclone_remote_exists,
+    remote_name_for_workspace,
+)
 from basic_memory.cli.commands.cloud.rclone_installer import (
    RcloneInstallError,
    install_rclone,
 )
+from basic_memory.mcp.project_context import get_available_workspaces
+from basic_memory.schemas.cloud import (
+    WorkspaceInfo,
+    format_workspace_choices,
+    format_workspace_selection_choices,
+    workspace_matches_exact_identifier,
+)

 console = Console()


+def _resolve_setup_workspace(identifier: str) -> WorkspaceInfo:
+    """Resolve a workspace identifier (slug, name, or tenant_id) for setup.
+
+    Errors with copyable choices when the identifier matches zero or multiple
+    workspaces, so the user can disambiguate.
+    """
+    workspaces = run_with_cleanup(get_available_workspaces())
+    if not workspaces:
+        console.print("[red]No accessible cloud workspaces found for this account[/red]")
+        raise typer.Exit(1)
+
+    matches = [ws for ws in workspaces if workspace_matches_exact_identifier(ws, identifier)]
+    if len(matches) == 1:
+        return matches[0]
+
+    if not matches:
+        console.print(f"[red]No workspace matches '{identifier}'[/red]")
+        console.print("\nAvailable workspaces:")
+        console.print(format_workspace_choices(workspaces))
+    else:
+        console.print(f"[red]'{identifier}' matches multiple workspaces[/red]")
+        console.print("\nDisambiguate with the workspace slug or tenant_id:")
+        console.print(format_workspace_selection_choices(matches))
+    raise typer.Exit(1)
+
+
@cloud_app.command()
 def login():
    """Authenticate with WorkOS using OAuth Device Authorization flow."""
@@ -164,13 +201,28 @@ def status() -> None:


@cloud_app.command("setup")
-def setup() -> None:
+def setup(
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help="Set up sync for a specific workspace (slug, name, or tenant_id). "
+        "Omit for your default workspace.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Reconfigure an rclone remote that already exists (mints new credentials).",
+    ),
+) -> None:
    """Set up cloud sync by installing rclone and configuring credentials.

-    After setup, use project commands for syncing:
-      bm project add <name> --cloud --local-path ~/projects/<name>
-      bm project bisync --name <name> --resync  # First time
-      bm project bisync --name <name>            # Subsequent syncs
+    Run once per workspace you sync. The default workspace uses the
+    'basic-memory-cloud' remote; other (e.g. Team) workspaces each get their own
+    tenant-scoped remote, since Tigris credentials are bucket-scoped.
+
+    After setup, use the cloud sync commands:
+      bm cloud pull --name <name>   # fetch cloud changes (Team-safe)
+      bm cloud push --name <name>   # upload local changes (Team-safe)
    """
    console.print("[bold blue]Basic Memory Cloud Setup[/bold blue]")
    console.print("Setting up cloud sync with rclone...\n")
@@ -180,35 +232,60 @@ def setup() -> None:
        console.print("[blue]Step 1: Installing rclone...[/blue]")
        install_rclone()

-        # Step 2: Get tenant info
+        # --- Resolve target workspace ---
+        # Trigger: --workspace given. Why: Tigris keys are tenant-scoped, so a
+        # non-default workspace needs its own bucket + remote. Outcome: scope the
+        # mount-info/credentials calls and name the remote after the workspace.
+        if workspace is not None:
+            target = _resolve_setup_workspace(workspace)
+            workspace_id: str | None = target.tenant_id
+            remote_name = remote_name_for_workspace(target.slug, is_default=target.is_default)
+            console.print(f"[dim]Workspace: {target.name} ({target.slug})[/dim]")
+        else:
+            workspace_id = None  # default tenant
+            remote_name = remote_name_for_workspace(None, is_default=True)
+
+        # Trigger: the target rclone remote already exists.
+        # Why: re-running setup mints new credentials and overwrites the remote,
+        # which would silently repoint it — e.g. clobbering the shared
+        # basic-memory-cloud remote that served another tenant. Checked BEFORE
+        # minting so an abort wastes no credentials.
+        # Outcome: stop unless the user explicitly opts in with --force.
+        if rclone_remote_exists(remote_name) and not force:
+            console.print(f"[red]rclone remote '{remote_name}' is already configured.[/red]")
+            console.print(
+                "Re-running setup mints new credentials and overwrites it. "
+                "Pass --force to reconfigure."
+            )
+            raise typer.Exit(1)
+
+        # Step 2: Get tenant info (scoped to the target workspace when given)
        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
-        tenant_info = run_with_cleanup(get_mount_info())
+        tenant_info = run_with_cleanup(get_mount_info(workspace_id=workspace_id))
        console.print(f"[green]Found tenant: {tenant_info.tenant_id}[/green]")

-        # Step 3: Generate credentials
+        # Step 3: Generate credentials for that tenant's bucket
        console.print("\n[blue]Step 3: Generating sync credentials...[/blue]")
        creds = run_with_cleanup(generate_mount_credentials(tenant_info.tenant_id))
        console.print("[green]Generated secure credentials[/green]")

-        # Step 4: Configure rclone remote
+        # Step 4: Configure the tenant's rclone remote
        console.print("\n[blue]Step 4: Configuring rclone remote...[/blue]")
        configure_rclone_remote(
            access_key=creds.access_key,
            secret_key=creds.secret_key,
+            remote_name=remote_name,
        )

        console.print("\n[bold green]Cloud setup completed successfully![/bold green]")
        console.print("\n[bold]Next steps:[/bold]")
-        console.print("1. Add a project with local sync path:")
-        console.print("   bm project add research --cloud --local-path ~/Documents/research")
-        console.print("\n   Or configure sync for an existing project:")
+        console.print("1. Configure sync for a project:")
        console.print("   bm cloud sync-setup research ~/Documents/research")
-        console.print("\n2. Preview the initial sync (recommended):")
-        console.print("   bm project bisync --name research --resync --dry-run")
-        console.print("\n3. If all looks good, run the actual sync:")
-        console.print("   bm project bisync --name research --resync")
-        console.print("\n4. Subsequent syncs (no --resync needed):")
-        console.print("   bm project bisync --name research")
+        console.print("\n2. Preview a pull (recommended):")
+        console.print("   bm cloud pull --name research --dry-run")
+        console.print("\n3. Fetch cloud changes / upload local changes:")
+        console.print("   bm cloud pull --name research")
+        console.print("   bm cloud push --name research")
        console.print(
            "\n[dim]Tip: Always use --dry-run first to preview changes before syncing[/dim]"
        )
@@ -216,6 +293,8 @@ def setup() -> None:
    except (RcloneInstallError, BisyncError, CloudAPIError) as e:
        console.print(f"\n[red]Setup failed: {e}[/red]")
        raise typer.Exit(1)
+    except typer.Exit:
+        raise
    except Exception as e:
        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
        raise typer.Exit(1)
@@ -7,6 +7,7 @@ they are cloud-specific operations.

 import os
 from datetime import datetime
+from enum import Enum

 import typer
 from rich.console import Console
@@ -16,10 +17,19 @@ from basic_memory.cli.commands.cloud.bisync_commands import get_mount_info
 from basic_memory.cli.commands.cloud.rclone_commands import (
    RcloneError,
    SyncProject,
+    TransferDirection,
+    TransferPlan,
    get_project_bisync_state,
    project_bisync,
    project_check,
+    project_diff,
    project_sync,
+    project_transfer,
+)
+from basic_memory.cli.commands.cloud.rclone_config import (
+    DEFAULT_RCLONE_REMOTE,
+    rclone_remote_exists,
+    remote_name_for_workspace,
 )
 from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.routing import force_routing
@@ -27,7 +37,12 @@ from basic_memory.config import BasicMemoryConfig, ConfigManager, ProjectEntry
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.clients import ProjectClient
 from basic_memory.mcp.project_context import get_available_workspaces
-from basic_memory.schemas.cloud import WorkspaceInfo
+from basic_memory.schemas.cloud import (
+    WorkspaceInfo,
+    format_workspace_choices,
+    format_workspace_selection_choices,
+    workspace_matches_exact_identifier,
+)
 from basic_memory.schemas.project_info import ProjectItem
 from basic_memory.utils import generate_permalink, normalize_project_path

@@ -35,9 +50,34 @@ console = Console()

 TEAM_WORKSPACE_BISYNC_UNSUPPORTED = (
    "The bisync operation is only supported on Personal workspaces.\n"
-    "Use `bm cloud sync --name {name}` instead."
+    "Use `bm cloud pull --name {name}` / `bm cloud push --name {name}` instead."
 )

+TEAM_WORKSPACE_SYNC_UNSUPPORTED = (
+    "The sync operation mirrors local onto the shared bucket and can delete a "
+    "teammate's files, so it is only supported on Personal workspaces.\n"
+    "Use `bm cloud pull --name {name}` (fetch) / `bm cloud push --name {name}` "
+    "(additive upload) instead."
+)
+
+
+class ConflictStrategy(str, Enum):
+    """How push/pull resolves files that differ on both sides.
+
+    Default is ``fail``: surface the conflicts and abort before transferring,
+    leaving the user to re-run with an explicit resolution — like git refusing
+    to clobber local changes.
+
+    This is the Typer-facing enum; the engine in ``rclone_commands`` accepts the
+    same values as a ``ConflictStrategy`` Literal. ``_run_directional_transfer``
+    bridges the two by passing ``on_conflict.value``. Keep the values in sync.
+    """
+
+    fail = "fail"
+    keep_local = "keep-local"
+    keep_cloud = "keep-cloud"
+    keep_both = "keep-both"
+

 # --- Shared helpers ---

@@ -59,12 +99,41 @@ def _require_cloud_credentials(config: BasicMemoryConfig) -> None:
    raise typer.Exit(1)


-async def _get_workspace_for_project(name: str, config: BasicMemoryConfig) -> WorkspaceInfo:
-    """Resolve the cloud workspace targeted by a project-scoped sync command."""
+async def _get_workspace_for_project(
+    name: str,
+    config: BasicMemoryConfig,
+    *,
+    workspace_override: str | None = None,
+) -> WorkspaceInfo:
+    """Resolve the cloud workspace targeted by a project-scoped sync command.
+
+    ``workspace_override`` (a slug, name, or tenant_id, e.g. from ``--workspace``)
+    takes precedence over config, letting the user disambiguate a project name
+    that exists in more than one workspace.
+    """
    workspaces = await get_available_workspaces()
    if not workspaces:
        raise ValueError("No accessible cloud workspaces found for this account")

+    # An explicit override wins over config — this is how the user disambiguates.
+    if workspace_override is not None:
+        matches = [
+            item
+            for item in workspaces
+            if workspace_matches_exact_identifier(item, workspace_override)
+        ]
+        if len(matches) == 1:
+            return matches[0]
+        if not matches:
+            raise ValueError(
+                f"No accessible workspace matches '{workspace_override}'.\n"
+                f"{format_workspace_choices(workspaces)}"
+            )
+        raise ValueError(
+            f"'{workspace_override}' matches multiple workspaces; use a slug or tenant_id:\n"
+            f"{format_workspace_selection_choices(matches)}"
+        )
+
    entry = config.projects.get(name)
    workspace_id = entry.workspace_id if entry and entry.workspace_id else config.default_workspace
    if workspace_id:
@@ -92,8 +161,18 @@ async def _get_workspace_for_project(name: str, config: BasicMemoryConfig) -> Wo
    )


-def _require_personal_workspace(name: str, config: BasicMemoryConfig) -> WorkspaceInfo:
-    """Exit before bisync work when the target workspace is not personal."""
+def _require_personal_workspace(
+    name: str,
+    config: BasicMemoryConfig,
+    *,
+    unsupported_message: str = TEAM_WORKSPACE_BISYNC_UNSUPPORTED,
+) -> WorkspaceInfo:
+    """Exit before mirror work when the target workspace is not personal.
+
+    Used to gate the destructive mirror operations (`sync`, `bisync`) to
+    Personal workspaces. ``unsupported_message`` lets each command point Team
+    users at the right Team-safe alternative.
+    """
    try:
        workspace = run_with_cleanup(_get_workspace_for_project(name, config))
    except Exception as exc:
@@ -101,15 +180,21 @@ def _require_personal_workspace(name: str, config: BasicMemoryConfig) -> Workspa
        raise typer.Exit(1)

    if workspace.workspace_type != "personal":
-        console.print(f"[red]{TEAM_WORKSPACE_BISYNC_UNSUPPORTED.format(name=name)}[/red]")
+        console.print(f"[red]{unsupported_message.format(name=name)}[/red]")
        raise typer.Exit(1)

    return workspace


-async def _get_cloud_project(name: str) -> ProjectItem | None:
-    """Fetch a project by name from the cloud API."""
-    async with get_client(project_name=name) as client:
+async def _get_cloud_project(name: str, *, workspace_id: str | None = None) -> ProjectItem | None:
+    """Fetch a project by name from the cloud API.
+
+    ``workspace_id`` routes the lookup to a specific tenant so the project
+    metadata comes from the same workspace the transfer targets (otherwise
+    get_client would resolve the workspace from config/default and could read a
+    different tenant — see #920 review).
+    """
+    async with get_client(project_name=name, workspace=workspace_id) as client:
        projects_list = await ProjectClient(client).list_projects()
        for proj in projects_list.projects:
            if generate_permalink(proj.name) == generate_permalink(name):
@@ -118,10 +203,17 @@ async def _get_cloud_project(name: str) -> ProjectItem | None:


 def _get_sync_project(
-    name: str, config: BasicMemoryConfig, project_data: ProjectItem
+    name: str,
+    config: BasicMemoryConfig,
+    project_data: ProjectItem,
+    *,
+    remote_name: str = DEFAULT_RCLONE_REMOTE,
 ) -> tuple[SyncProject, str | None]:
    """Build a SyncProject and resolve local_sync_path from config.

+    ``remote_name`` selects which tenant-scoped rclone remote the project routes
+    through (default tenant vs a team workspace remote).
+
    Returns (sync_project, local_sync_path). Exits if no local_sync_path configured.
    """
    sync_entry = config.projects.get(name)
@@ -137,6 +229,7 @@ def _get_sync_project(
        name=project_data.name,
        path=normalize_project_path(project_data.path),
        local_sync_path=local_sync_path,
+        remote_name=remote_name,
    )
    return sync_project, local_sync_path

@@ -150,7 +243,11 @@ def sync_project_command(
    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without syncing"),
    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
 ) -> None:
-    """One-way sync: local -> cloud (make cloud identical to local).
+    """One-way mirror: local -> cloud (make cloud identical to local).
+
+    Personal workspaces only. This deletes cloud files not present locally, so
+    on Team workspaces use `bm cloud push` (additive upload) / `bm cloud pull`
+    (fetch) instead.

    Example:
      bm cloud sync --name research
@@ -158,9 +255,13 @@ def sync_project_command(
    """
    config = ConfigManager().config
    _require_cloud_credentials(config)
+    _require_personal_workspace(name, config, unsupported_message=TEAM_WORKSPACE_SYNC_UNSUPPORTED)

    try:
-        # Get tenant info for bucket name
+        # Get tenant info for bucket name.
+        # TODO(#919): scope to the project's workspace like push/pull. Safe for now
+        # because these mirror commands are gated to the (default-tenant) Personal
+        # workspace, so the default mount info is correct.
        tenant_info = run_with_cleanup(get_mount_info())
        bucket_name = tenant_info.bucket_name

@@ -191,6 +292,219 @@ def sync_project_command(
        raise typer.Exit(1)


+def _print_conflict_abort(name: str, direction: TransferDirection, plan: TransferPlan) -> None:
+    """Explain a conflict abort and how to resolve it (git-pull style)."""
+    console.print(
+        f"[red]{direction.capitalize()} aborted: {len(plan.conflicts)} file(s) differ between "
+        f"local and cloud.[/red]"
+    )
+    for path in plan.conflicts:
+        console.print(f"  [yellow]*[/yellow] {path}")
+    console.print("\nRe-run with one of:")
+    console.print("  [dim]--on-conflict keep-cloud[/dim]  take the cloud version")
+    console.print("  [dim]--on-conflict keep-local[/dim]  keep your local version")
+    console.print(
+        "  [dim]--on-conflict keep-both[/dim]   keep both (writes <name>.conflict-<date>)"
+    )
+
+
+def _run_directional_transfer(
+    name: str,
+    direction: TransferDirection,
+    *,
+    on_conflict: ConflictStrategy,
+    dry_run: bool,
+    verbose: bool,
+    workspace: str | None = None,
+) -> None:
+    """Shared orchestration for `bm cloud push` / `bm cloud pull`.
+
+    Detects conflicts first, then aborts (the default) or applies the chosen
+    resolution. Uses additive `rclone copy`, so it never deletes on the
+    destination — safe for Team workspaces and therefore not gated.
+
+    Routes through the resolved workspace's own tenant-scoped rclone remote, so a
+    Team project reads/writes the right bucket (see #919).
+    """
+    config = ConfigManager().config
+    _require_cloud_credentials(config)
+
+    try:
+        # --- Resolve the target workspace and its tenant-scoped remote ---
+        # Tigris credentials are bucket/tenant-scoped, so each workspace has its
+        # own rclone remote. Resolve which workspace this project belongs to
+        # (config or --workspace override) before touching any bucket.
+        try:
+            target_workspace = run_with_cleanup(
+                _get_workspace_for_project(name, config, workspace_override=workspace)
+            )
+        except Exception as exc:
+            console.print(f"[red]Error resolving workspace for project '{name}': {exc}[/red]")
+            raise typer.Exit(1)
+
+        remote_name = remote_name_for_workspace(
+            target_workspace.slug, is_default=target_workspace.is_default
+        )
+
+        # Trigger: the workspace's remote has not been configured yet.
+        # Why: provisioning mints tenant-scoped credentials and must be explicit
+        # (no surprise key generation); push/pull only transfer.
+        # Outcome: stop with the exact setup command for this workspace.
+        if not rclone_remote_exists(remote_name):
+            setup_target = (
+                "" if target_workspace.is_default else f" --workspace {target_workspace.slug}"
+            )
+            console.print(f"[red]Workspace '{target_workspace.slug}' is not set up for sync.[/red]")
+            console.print(f"\nRun: bm cloud setup{setup_target}")
+            raise typer.Exit(1)
+
+        # Get tenant info for bucket name, scoped to the resolved workspace
+        tenant_info = run_with_cleanup(get_mount_info(workspace_id=target_workspace.tenant_id))
+        bucket_name = tenant_info.bucket_name
+
+        # Get project info from the same workspace we resolved above, so the
+        # project path and the bucket/remote all refer to one tenant.
+        with force_routing(cloud=True):
+            project_data = run_with_cleanup(
+                _get_cloud_project(name, workspace_id=target_workspace.tenant_id)
+            )
+        if not project_data:
+            console.print(f"[red]Error: Project '{name}' not found[/red]")
+            raise typer.Exit(1)
+
+        sync_project, _ = _get_sync_project(name, config, project_data, remote_name=remote_name)
+
+        # --- Detect before transferring ---
+        plan = project_diff(sync_project, bucket_name, direction)
+
+        # Trigger: rclone could not read/hash some files.
+        # Why: comparing is the whole basis for a safe transfer — never guess.
+        # Outcome: abort before moving any bytes.
+        if plan.errors:
+            console.print(
+                f"[red]{direction.capitalize()} aborted: rclone could not compare "
+                f"{len(plan.errors)} file(s)[/red]"
+            )
+            for path in plan.errors:
+                console.print(f"  [red]![/red] {path}")
+            raise typer.Exit(1)
+
+        # Trigger: files differ on both sides and the user chose no resolution.
+        # Why: "no surprises" — never silently pick a winner.
+        # Outcome: list the conflicts and exit, like git refusing to clobber.
+        if plan.conflicts and on_conflict is ConflictStrategy.fail:
+            _print_conflict_abort(name, direction, plan)
+            raise typer.Exit(1)
+
+        # --- Transfer ---
+        arrow = "cloud -> local" if direction == "pull" else "local -> cloud"
+        console.print(f"[blue]{direction.capitalize()} {name} ({arrow})...[/blue]")
+
+        conflict_suffix = datetime.now().strftime("%Y%m%d-%H%M%S")
+        success = project_transfer(
+            sync_project,
+            bucket_name,
+            direction,
+            plan,
+            strategy=on_conflict.value,
+            conflict_suffix=conflict_suffix,
+            dry_run=dry_run,
+            verbose=verbose,
+        )
+
+        if not success:
+            console.print(f"[red]{name} {direction} failed[/red]")
+            raise typer.Exit(1)
+
+        console.print(f"[green]{name} {direction} completed successfully[/green]")
+
+        # Without a sync baseline (see #862) we cannot tell an intentional delete
+        # from a file the other side simply never had, so deletions never sync.
+        if plan.dest_only:
+            kept_on = "local" if direction == "pull" else "cloud"
+            console.print(
+                f"[dim]{len(plan.dest_only)} file(s) exist only on {kept_on} and were left "
+                "untouched (deletions are not propagated).[/dim]"
+            )
+
+    except RcloneError as e:
+        console.print(f"[red]{direction.capitalize()} error: {e}[/red]")
+        raise typer.Exit(1)
+    except typer.Exit:
+        # Already-handled exits (not found, conflicts, errors) propagate cleanly.
+        raise
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("pull")
+def pull_project_command(
+    name: str = typer.Option(..., "--name", "--project", help="Project name to pull"),
+    on_conflict: ConflictStrategy = typer.Option(
+        ConflictStrategy.fail,
+        "--on-conflict",
+        help="Resolve files that differ on both sides (default: fail and list them)",
+    ),
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help="Workspace (slug, name, or tenant_id) when the project name is ambiguous",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without pulling"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """Fetch cloud changes into local (cloud -> local), git-pull style.
+
+    Additive and Team-safe: downloads new/changed cloud files and never deletes
+    local files. A file that differs on both sides is a conflict; by default
+    pull aborts and lists them. Deletions are not propagated (see #862).
+
+    Examples:
+      bm cloud pull --name research
+      bm cloud pull --name research --dry-run
+      bm cloud pull --name research --on-conflict keep-cloud
+      bm cloud pull --name research --workspace acme
+    """
+    _run_directional_transfer(
+        name, "pull", on_conflict=on_conflict, dry_run=dry_run, verbose=verbose, workspace=workspace
+    )
+
+
+@cloud_app.command("push")
+def push_project_command(
+    name: str = typer.Option(..., "--name", "--project", help="Project name to push"),
+    on_conflict: ConflictStrategy = typer.Option(
+        ConflictStrategy.fail,
+        "--on-conflict",
+        help="Resolve files that differ on both sides (default: fail and list them)",
+    ),
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help="Workspace (slug, name, or tenant_id) when the project name is ambiguous",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without pushing"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """Upload local changes to cloud (local -> cloud), additive and Team-safe.
+
+    Uploads new/changed local files and never deletes cloud files. A file that
+    differs on both sides is a conflict; by default push aborts and lists them
+    (like git rejecting a push when the remote is ahead — pull first). Deletions
+    are not propagated (see #862).
+
+    Examples:
+      bm cloud push --name research
+      bm cloud push --name research --dry-run
+      bm cloud push --name research --on-conflict keep-local
+      bm cloud push --name research --workspace acme
+    """
+    _run_directional_transfer(
+        name, "push", on_conflict=on_conflict, dry_run=dry_run, verbose=verbose, workspace=workspace
+    )
+
+
@cloud_app.command("bisync")
 def bisync_project_command(
    name: str = typer.Option(..., "--name", "--project", help="Project name to bisync"),
@@ -210,7 +524,10 @@ def bisync_project_command(
    _require_personal_workspace(name, config)

    try:
-        # Get tenant info for bucket name
+        # Get tenant info for bucket name.
+        # TODO(#919): scope to the project's workspace like push/pull. Safe for now
+        # because these mirror commands are gated to the (default-tenant) Personal
+        # workspace, so the default mount info is correct.
        tenant_info = run_with_cleanup(get_mount_info())
        bucket_name = tenant_info.bucket_name

@@ -268,7 +585,10 @@ def check_project_command(
    _require_cloud_credentials(config)

    try:
-        # Get tenant info for bucket name
+        # Get tenant info for bucket name.
+        # TODO(#919): scope to the project's workspace like push/pull. Safe for now
+        # because these mirror commands are gated to the (default-tenant) Personal
+        # workspace, so the default mount info is correct.
        tenant_info = run_with_cleanup(get_mount_info())
        bucket_name = tenant_info.bucket_name

@@ -395,9 +715,15 @@ def setup_project_sync(

        console.print(f"[green]Sync configured for project '{name}'[/green]")
        console.print(f"\nLocal sync path: {resolved_path}")
+        # Lead with the Team-safe additive commands (work on any workspace); the
+        # `sync`/`bisync` mirrors are Personal-workspace-only.
        console.print("\nNext steps:")
-        console.print(f"  1. Preview: bm cloud sync --name {name} --dry-run")
-        console.print(f"  2. Sync: bm cloud sync --name {name}")
+        console.print(f"  1. Preview a pull: bm cloud pull --name {name} --dry-run")
+        console.print(f"  2. Fetch from cloud: bm cloud pull --name {name}")
+        console.print(f"  3. Upload local changes: bm cloud push --name {name}")
+        console.print(
+            f"  Personal workspaces can also mirror with: bm cloud bisync --name {name} --resync"
+        )
    except Exception as e:
        console.print(f"[red]Error configuring sync: {str(e)}[/red]")
        raise typer.Exit(1)
@@ -2,7 +2,8 @@

 This module provides simplified, project-scoped rclone operations:
 - Each project syncs independently
- Uses single "basic-memory-cloud" remote (not tenant-specific)
+- Routes through the project's tenant-scoped remote (SyncProject.remote_name);
+  the default tenant keeps "basic-memory-cloud", others use their own (see #919)
 - Balanced defaults from SPEC-8 Phase 4 testing
 - Per-project bisync state tracking

@@ -11,10 +12,10 @@ Replaces tenant-wide sync with project-scoped workflows.

 import re
 import subprocess
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from functools import lru_cache
-from pathlib import Path
-from typing import Callable, Optional, Protocol
+from pathlib import Path, PurePosixPath
+from typing import Callable, Literal, Optional, Protocol

 from loguru import logger
 from rich.console import Console
@@ -42,6 +43,7 @@ TIGRIS_CONSISTENCY_HEADERS = [
 class RunResult(Protocol):
    returncode: int
    stdout: str
+    stderr: str


 RunFunc = Callable[..., RunResult]
@@ -112,11 +114,15 @@ class SyncProject:
        name: Project name
        path: Cloud path (e.g., "app/data/research")
        local_sync_path: Local directory for syncing (optional)
+        remote_name: rclone remote serving this project's tenant bucket. Defaults
+            to the legacy single remote; team/non-default workspaces use their own
+            (see remote_name_for_workspace).
    """

    name: str
    path: str
    local_sync_path: Optional[str] = None
+    remote_name: str = "basic-memory-cloud"


 def get_bmignore_filter_path() -> Path:
@@ -178,10 +184,98 @@ def get_project_remote(project: SyncProject, bucket_name: str) -> str:
        The API returns paths like "/app/data/basic-memory-llc" because the S3 bucket
        is mounted at /app/data on the fly machine. We need to strip the /app/data/
        prefix to get the actual S3 path within the bucket.
+
+        The remote name comes from the project so non-default/team workspaces route
+        through their own tenant-scoped remote (see #919).
    """
    # Normalize path to strip /app/data/ mount point prefix
    cloud_path = normalize_project_path(project.path).lstrip("/")
-    return f"basic-memory-cloud:{bucket_name}/{cloud_path}"
+    return f"{project.remote_name}:{bucket_name}/{cloud_path}"
+
+
+# --- Directional transfer primitives (push / pull) ---
+#
+# These power the Team-safe `bm cloud push` / `bm cloud pull` commands. Unlike
+# the mirror operations (`sync`/`bisync`), they use `rclone copy` so they never
+# delete on the destination, and conflicts are surfaced to the caller rather
+# than silently resolved. See issue #858 for the full design rationale.
+
+# push = local -> cloud, pull = cloud -> local.
+TransferDirection = Literal["push", "pull"]
+
+# How a directional transfer treats files that differ on both sides. "fail" is
+# the safe default: the caller is expected to abort before any transfer runs.
+ConflictStrategy = Literal["fail", "keep-local", "keep-cloud", "keep-both"]
+
+
+@dataclass
+class TransferPlan:
+    """Classification of how local and cloud differ for a directional transfer.
+
+    Built from ``rclone check --combined``. Paths are relative to the project
+    root. ``conflicts`` are files present on both sides with differing content —
+    without a sync baseline (see #862) every divergence is a conflict, because
+    we cannot tell a teammate's edit from a stale local copy.
+    """
+
+    new: list[str] = field(default_factory=list)  # only on source → safe to bring over
+    conflicts: list[str] = field(default_factory=list)  # differ on both sides
+    dest_only: list[str] = field(default_factory=list)  # only on destination → left untouched
+    errors: list[str] = field(default_factory=list)  # rclone could not read/hash
+
+
+def _transfer_endpoints(project: SyncProject, bucket_name: str) -> tuple[str, str]:
+    """Return (local_path, remote_path) strings for a project's transfer.
+
+    Raises:
+        RcloneError: If the project has no local_sync_path configured.
+    """
+    if not project.local_sync_path:
+        raise RcloneError(f"Project {project.name} has no local_sync_path configured")
+    local_path = str(Path(project.local_sync_path).expanduser())
+    remote_path = get_project_remote(project, bucket_name)
+    return local_path, remote_path
+
+
+def _build_transfer_cmd(
+    operation: str,
+    source: str,
+    dest: str,
+    *,
+    filter_path: Path,
+    dry_run: bool,
+    verbose: bool,
+    extra_flags: tuple[str, ...] = (),
+) -> list[str]:
+    """Build an rclone sync/copy command with the shared Basic Memory flags.
+
+    All directional transfers share the same tail: Tigris consistency headers,
+    the .bmignore filter, and --local-no-preallocate (a no-op when local is the
+    source, required when local is the destination on pull — see rclone#6801).
+    """
+    cmd = [
+        "rclone",
+        operation,
+        source,
+        dest,
+        *TIGRIS_CONSISTENCY_HEADERS,
+        "--filter-from",
+        str(filter_path),
+        # Prevent NUL byte padding on virtual filesystems (e.g. Google Drive File Stream)
+        # See: rclone/rclone#6801
+        "--local-no-preallocate",
+        *extra_flags,
+    ]
+
+    if verbose:
+        cmd.append("--verbose")
+    else:
+        cmd.append("--progress")
+
+    if dry_run:
+        cmd.append("--dry-run")
+
+    return cmd


 def project_sync(
@@ -219,24 +313,199 @@ def project_sync(
    remote_path = get_project_remote(project, bucket_name)
    filter_path = filter_path or get_bmignore_filter_path()

-    cmd = [
-        "rclone",
+    cmd = _build_transfer_cmd(
        "sync",
        str(local_path),
        remote_path,
+        filter_path=filter_path,
+        dry_run=dry_run,
+        verbose=verbose,
+    )
+
+    result = run(cmd, text=True)
+    return result.returncode == 0
+
+
+def _parse_check_combined(output: str) -> TransferPlan:
+    """Parse ``rclone check --combined`` output into a TransferPlan.
+
+    rclone emits one prefixed line per path (src is the transfer source):
+      ``=`` identical, ``+`` only on src, ``-`` only on dst, ``*`` differ,
+      ``!`` error reading/hashing. We ignore identical files.
+    """
+    plan = TransferPlan()
+    for line in output.splitlines():
+        symbol, _, path = line.partition(" ")
+        path = path.strip()
+        if not path:
+            continue
+        if symbol == "+":
+            plan.new.append(path)
+        elif symbol == "*":
+            plan.conflicts.append(path)
+        elif symbol == "-":
+            plan.dest_only.append(path)
+        elif symbol == "!":
+            plan.errors.append(path)
+        # "=" (identical) is intentionally dropped.
+    return plan
+
+
+def project_diff(
+    project: SyncProject,
+    bucket_name: str,
+    direction: TransferDirection,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
+) -> TransferPlan:
+    """Classify how local and cloud differ for a push/pull, without transferring.
+
+    Uses ``rclone check`` (content comparison) so the caller can surface
+    conflicts before any data moves. The source side depends on direction:
+    pull compares cloud→local, push compares local→cloud.
+
+    Raises:
+        RcloneError: If project has no local_sync_path configured or rclone not installed
+    """
+    check_rclone_installed(is_installed=is_installed)
+
+    local_path, remote_path = _transfer_endpoints(project, bucket_name)
+    filter_path = filter_path or get_bmignore_filter_path()
+
+    # Source/dest order matters: rclone check reports "+" for files only on the
+    # source, which is what we want to bring over.
+    source, dest = (remote_path, local_path) if direction == "pull" else (local_path, remote_path)
+
+    cmd = [
+        "rclone",
+        "check",
+        source,
+        dest,
        *TIGRIS_CONSISTENCY_HEADERS,
        "--filter-from",
        str(filter_path),
-        # Prevent NUL byte padding on virtual filesystems (e.g. Google Drive File Stream)
-        # See: rclone/rclone#6801
-        "--local-no-preallocate",
+        "--combined",
+        "-",
    ]

+    # rclone check exits non-zero when files differ — that's expected here, so we
+    # parse the combined listing rather than trusting the return code.
+    result = run(cmd, capture_output=True, text=True)
+    plan = _parse_check_combined(result.stdout)
+
+    # Trigger: non-zero exit AND the combined listing produced no entries at all.
+    # Why: a difference always yields +/-/*/! lines, so an empty listing on a
+    # non-zero exit means the check itself failed (auth, missing remote, network,
+    # bad filter) rather than finding zero differences. Without this guard the
+    # caller would see an empty plan, transfer nothing, and report success.
+    # Outcome: fail fast with rclone's stderr instead of a silent no-op.
+    if result.returncode != 0 and not (plan.new or plan.conflicts or plan.dest_only or plan.errors):
+        detail = result.stderr.strip() or f"rclone check exited with code {result.returncode}"
+        raise RcloneError(f"Failed to compare {project.name} with cloud: {detail}")
+
+    return plan
+
+
+def project_copy(
+    project: SyncProject,
+    bucket_name: str,
+    direction: TransferDirection,
+    *,
+    overwrite: bool,
+    dry_run: bool = False,
+    verbose: bool = False,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
+) -> bool:
+    """Additive transfer via ``rclone copy`` — never deletes on the destination.
+
+    Trigger: ``overwrite=False`` adds ``--ignore-existing`` so files already on
+    the destination are left as-is (used when the destination side wins a
+    conflict, and for the no-conflict fast path).
+    Why: keeps the loser's bytes intact unless the caller explicitly chose to
+    overwrite, matching the "no surprises" contract.
+
+    Raises:
+        RcloneError: If project has no local_sync_path configured or rclone not installed
+    """
+    check_rclone_installed(is_installed=is_installed)
+
+    local_path, remote_path = _transfer_endpoints(project, bucket_name)
+    filter_path = filter_path or get_bmignore_filter_path()
+
+    source, dest = (remote_path, local_path) if direction == "pull" else (local_path, remote_path)
+    # Overwrite mode compares by checksum so the transfer decision matches
+    # project_diff's content-based conflict detection (rclone check). Without
+    # --checksum, copy's default size+modtime comparison could skip a file the
+    # diff flagged as a conflict (same size, destination not older) — silently
+    # ignoring the user's explicit keep-cloud/keep-local choice. New-only mode
+    # uses --ignore-existing, which skips by existence so the comparison basis
+    # does not matter.
+    extra_flags = ("--checksum",) if overwrite else ("--ignore-existing",)
+
+    cmd = _build_transfer_cmd(
+        "copy",
+        source,
+        dest,
+        filter_path=filter_path,
+        dry_run=dry_run,
+        verbose=verbose,
+        extra_flags=extra_flags,
+    )
+
+    result = run(cmd, text=True)
+    return result.returncode == 0
+
+
+def _conflict_copy_name(rel_path: str, suffix: str) -> str:
+    """Insert a ``.conflict-<suffix>`` marker before the extension of a rel path."""
+    p = PurePosixPath(rel_path)
+    return str(p.with_name(f"{p.stem}.conflict-{suffix}{p.suffix}"))
+
+
+def project_copy_file(
+    project: SyncProject,
+    bucket_name: str,
+    direction: TransferDirection,
+    source_rel_path: str,
+    dest_rel_path: str,
+    *,
+    dry_run: bool = False,
+    verbose: bool = False,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+) -> bool:
+    """Copy a single file from source to destination under a (possibly renamed) path.
+
+    Used for the ``keep-both`` strategy: the incoming version is written beside
+    the destination's own copy as ``name.conflict-<date>`` so nothing is lost.
+
+    Raises:
+        RcloneError: If project has no local_sync_path configured or rclone not installed
+    """
+    check_rclone_installed(is_installed=is_installed)
+
+    local_path, remote_path = _transfer_endpoints(project, bucket_name)
+    source_root, dest_root = (
+        (remote_path, local_path) if direction == "pull" else (local_path, remote_path)
+    )
+
+    cmd = [
+        "rclone",
+        "copyto",
+        f"{source_root}/{source_rel_path}",
+        f"{dest_root}/{dest_rel_path}",
+        *TIGRIS_CONSISTENCY_HEADERS,
+        # Matches _build_transfer_cmd: on pull this writes the conflict copy to
+        # the local filesystem, where this prevents NUL byte padding on virtual
+        # filesystems (e.g. Google Drive File Stream). See rclone/rclone#6801.
+        "--local-no-preallocate",
+    ]
    if verbose:
        cmd.append("--verbose")
-    else:
-        cmd.append("--progress")
-
    if dry_run:
        cmd.append("--dry-run")

@@ -244,6 +513,72 @@ def project_sync(
    return result.returncode == 0


+def _strategy_overwrites_dest(direction: TransferDirection, strategy: ConflictStrategy) -> bool:
+    """True when the strategy lets the source side overwrite the destination.
+
+    The source side is cloud on pull, local on push. "keep-cloud" wins on pull,
+    "keep-local" wins on push; otherwise the destination is preserved.
+    """
+    if strategy == "keep-cloud":
+        return direction == "pull"
+    if strategy == "keep-local":
+        return direction == "push"
+    return False  # "fail" (no conflicts) and "keep-both" never overwrite existing dest files
+
+
+def project_transfer(
+    project: SyncProject,
+    bucket_name: str,
+    direction: TransferDirection,
+    plan: TransferPlan,
+    *,
+    strategy: ConflictStrategy = "fail",
+    conflict_suffix: str = "",
+    dry_run: bool = False,
+    verbose: bool = False,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
+) -> bool:
+    """Execute a directional transfer for the chosen conflict strategy.
+
+    Callers detect conflicts with ``project_diff`` first and abort when
+    ``strategy == "fail"`` and conflicts exist; this function assumes that gate
+    has already passed and applies the resolution.
+    """
+    # keep-both: preserve the destination's version and drop the incoming one
+    # beside it as a conflict copy, then do an additive (new-only) pass.
+    if strategy == "keep-both":
+        for rel_path in plan.conflicts:
+            dest_rel = _conflict_copy_name(rel_path, conflict_suffix)
+            copied = project_copy_file(
+                project,
+                bucket_name,
+                direction,
+                rel_path,
+                dest_rel,
+                dry_run=dry_run,
+                verbose=verbose,
+                run=run,
+                is_installed=is_installed,
+            )
+            if not copied:
+                return False
+
+    overwrite = _strategy_overwrites_dest(direction, strategy)
+    return project_copy(
+        project,
+        bucket_name,
+        direction,
+        overwrite=overwrite,
+        dry_run=dry_run,
+        verbose=verbose,
+        run=run,
+        is_installed=is_installed,
+        filter_path=filter_path,
+    )
+
+
 def project_bisync(
    project: SyncProject,
    bucket_name: str,
@@ -1,11 +1,14 @@
 """rclone configuration management for Basic Memory Cloud.

-This module provides simplified rclone configuration for SPEC-20.
-Uses a single "basic-memory-cloud" remote for all operations.
+This module owns rclone remote configuration and naming. The default tenant uses
+the "basic-memory-cloud" remote (from SPEC-20); non-default/team workspaces each
+get their own tenant-scoped remote via remote_name_for_workspace (see #919),
+since Tigris credentials are bucket-scoped.
 """

 import configparser
 import os
+import re
 import shutil
 from pathlib import Path
 from typing import Optional
@@ -61,25 +64,65 @@ def save_rclone_config(config: configparser.ConfigParser) -> None:
    console.print(f"[dim]Updated rclone config: {config_path}[/dim]")


+# The default remote serves the account's default tenant (back-compat with SPEC-20,
+# which used a single "basic-memory-cloud" remote). Non-default workspaces each get
+# their own remote, since Tigris credentials are bucket/tenant-scoped (see #919).
+DEFAULT_RCLONE_REMOTE = "basic-memory-cloud"
+
+
+# rclone remote section names allow letters, digits, hyphens, and underscores.
+# The slug comes from the cloud API (a trust boundary), so validate it before
+# splicing it into a remote name to avoid a broken/unusable rclone.conf section.
+_SAFE_SLUG = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def remote_name_for_workspace(slug: str | None, *, is_default: bool) -> str:
+    """Return the rclone remote name for a workspace.
+
+    The default workspace keeps the legacy ``basic-memory-cloud`` remote so
+    existing setups keep working; other workspaces get ``basic-memory-cloud-<slug>``.
+
+    Raises:
+        RcloneConfigError: If a non-default workspace slug contains characters
+            that are not valid in an rclone remote name.
+    """
+    if is_default or not slug:
+        return DEFAULT_RCLONE_REMOTE
+    if not _SAFE_SLUG.match(slug):
+        raise RcloneConfigError(
+            f"Workspace slug '{slug}' cannot be used as an rclone remote name "
+            "(allowed: letters, digits, hyphens, underscores)."
+        )
+    return f"{DEFAULT_RCLONE_REMOTE}-{slug}"
+
+
+def rclone_remote_exists(remote_name: str) -> bool:
+    """Return whether an rclone remote section is already configured."""
+    return load_rclone_config().has_section(remote_name)
+
+
 def configure_rclone_remote(
    access_key: str,
    secret_key: str,
    endpoint: str = "https://fly.storage.tigris.dev",
    region: str = "auto",
+    remote_name: str = DEFAULT_RCLONE_REMOTE,
 ) -> str:
-    """Configure single rclone remote named 'basic-memory-cloud'.
+    """Configure an rclone remote for one tenant's bucket.

-    This is the simplified approach from SPEC-20 that uses one remote
-    for all Basic Memory cloud operations (not tenant-specific).
+    Each tenant (personal or team) has its own bucket-scoped credentials, so a
+    remote maps 1:1 to a tenant. The default tenant keeps ``basic-memory-cloud``;
+    other workspaces pass ``remote_name`` from :func:`remote_name_for_workspace`.

    Args:
        access_key: S3 access key ID
        secret_key: S3 secret access key
        endpoint: S3-compatible endpoint URL
        region: S3 region (default: auto)
+        remote_name: rclone remote section name to write

    Returns:
-        The remote name: "basic-memory-cloud"
+        The remote name that was configured
    """
    # Backup existing config
    backup_rclone_config()
@@ -87,24 +130,21 @@ def configure_rclone_remote(
    # Load existing config
    config = load_rclone_config()

-    # Single remote name (not tenant-specific)
-    REMOTE_NAME = "basic-memory-cloud"
-
    # Add/update the remote section
-    if not config.has_section(REMOTE_NAME):
-        config.add_section(REMOTE_NAME)
+    if not config.has_section(remote_name):
+        config.add_section(remote_name)

-    config.set(REMOTE_NAME, "type", "s3")
-    config.set(REMOTE_NAME, "provider", "Other")
-    config.set(REMOTE_NAME, "access_key_id", access_key)
-    config.set(REMOTE_NAME, "secret_access_key", secret_key)
-    config.set(REMOTE_NAME, "endpoint", endpoint)
-    config.set(REMOTE_NAME, "region", region)
+    config.set(remote_name, "type", "s3")
+    config.set(remote_name, "provider", "Other")
+    config.set(remote_name, "access_key_id", access_key)
+    config.set(remote_name, "secret_access_key", secret_key)
+    config.set(remote_name, "endpoint", endpoint)
+    config.set(remote_name, "region", region)
    # Prevent unnecessary encoding of filenames (only encode slashes and invalid UTF-8)
    # This prevents files with spaces like "Hello World.md" from being quoted
-    config.set(REMOTE_NAME, "encoding", "Slash,InvalidUtf8")
+    config.set(remote_name, "encoding", "Slash,InvalidUtf8")
    # Save updated config
    save_rclone_config(config)

-    console.print(f"[green]Configured rclone remote: {REMOTE_NAME}[/green]")
-    return REMOTE_NAME
+    console.print(f"[green]Configured rclone remote: {remote_name}[/green]")
+    return remote_name
@@ -1,13 +1,14 @@
 """Read note tool for Basic Memory MCP server."""

 from textwrap import dedent
-from typing import Optional, Literal, cast
+from typing import Annotated, Optional, Literal, cast

 import logfire
 import yaml

 from loguru import logger
 from fastmcp import Context
+from pydantic import AliasChoices, Field

 from basic_memory.config import ConfigManager
 from basic_memory.mcp.project_context import (
@@ -20,6 +21,17 @@ from basic_memory.mcp.tools.search import search_notes
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path

+# The title-match fallback exists to find THE note by exact title, so it scans
+# fixed-size pages of title results instead of the caller's page/page_size
+# (which apply only to the text-search suggestion listing).
+_TITLE_LOOKUP_PAGE_SIZE = 10
+
+# Hard safety cap on title-lookup pages. The loop normally stops as soon as an
+# exact match is found or results run out (has_more=False); the cap only bounds
+# pathological knowledge bases where hundreds of fuzzy titles contain the
+# queried phrase. Exhausting the cap falls through to the suggestion behavior.
+_TITLE_LOOKUP_MAX_PAGES = 10
+

 def _is_exact_title_match(identifier: str, title: str) -> bool:
    """Return True when identifier exactly matches a title (case-insensitive)."""
@@ -71,6 +83,21 @@ async def read_note(
    identifier: str,
    project: Optional[str] = None,
    project_id: Optional[str] = None,
+    # Accept common pagination aliases models reach for from training data
+    # (page_number/limit/per_page), matching the sibling navigation tools
+    # (search_notes, build_context, recent_activity). The schema advertises
+    # only the canonical names; aliases are silently mapped at validation time.
+    # `offset` is intentionally NOT aliased: offset is item-indexed (skip N
+    # items) while page is a 1-indexed page-number, so direct aliasing would
+    # return the wrong slice.
+    page: Annotated[
+        int,
+        Field(default=1, validation_alias=AliasChoices("page", "page_number")),
+    ] = 1,
+    page_size: Annotated[
+        int,
+        Field(default=10, validation_alias=AliasChoices("page_size", "limit", "per_page")),
+    ] = 10,
    output_format: Literal["text", "json"] = "text",
    include_frontmatter: bool = False,
    context: Context | None = None,
@@ -99,6 +126,14 @@ async def read_note(
                workspaces. Takes precedence over `project`. Get from list_memory_projects().
        identifier: The title or permalink of the note to read
                   Can be a full memory:// URL, a permalink, a title, or search text
+        page: Page of fallback-search results to use when the identifier does not
+            resolve to a note directly (default: 1). A direct or exact-title match
+            always returns the full note content — page/page_size never chunk the
+            note itself, and the title-match lookup pages through fixed-size pages
+            of title results until an exact match is found or results are
+            exhausted, regardless of page or page_size.
+        page_size: Number of fallback-search results per page (default: 10). When no
+            match is found, this caps how many related-note suggestions are listed.
        output_format: "text" returns markdown content or guidance text.
            "json" returns a structured object with title/permalink/file_path/content/frontmatter.
        include_frontmatter: When output_format="json", whether content should include the
@@ -122,6 +157,9 @@ async def read_note(
        # Read recent meeting notes
        read_note("team-docs", "Weekly Standup")

+        # Page through fallback-search suggestions when nothing matches directly
+        read_note("unknown topic", page=2, page_size=5)
+
    Raises:
        HTTPError: If project doesn't exist or is inaccessible
        SecurityError: If identifier attempts path traversal
@@ -130,6 +168,15 @@ async def read_note(
        If the exact note isn't found, this tool provides helpful suggestions
        including related notes, search commands, and note creation templates.
    """
+    # Trigger: page < 1 or page_size < 1 (e.g. page_size=0 or negative).
+    # Why: both flow into the fallback search's server-side slicing, where
+    #      non-positive values produce empty result pages with unreachable
+    #      pagination. Fail fast, matching search_notes/build_context.
+    if page < 1:
+        raise ValueError(f"page must be >= 1, got {page}")
+    if page_size < 1:
+        raise ValueError(f"page_size must be >= 1, got {page_size}")
+
    # Detect project from a memory URL or permalink prefix before routing.
    # project_id routes by external UUID, so it bypasses URL discovery entirely.
    if project is None and project_id is None:
@@ -147,6 +194,8 @@ async def read_note(
        tool_name="read_note",
        requested_project=project,
        requested_project_id=project_id,
+        page=page,
+        page_size=page_size,
        output_format=output_format,
        include_frontmatter=include_frontmatter,
    ):
@@ -245,7 +294,7 @@ async def read_note(
                ]

            async def _search_candidates(
-                identifier_text: str, *, title_only: bool
+                identifier_text: str, *, title_only: bool, lookup_page: int = 1
            ) -> dict[str, object]:
                # Trigger: direct entity resolution failed for the caller's identifier.
                # Why: search_notes applies the same memory:// normalization and tool-level
@@ -256,11 +305,24 @@ async def read_note(
                # Without this, project names that collide across workspaces could re-resolve
                # to a different tenant via the default-workspace fallback (CLI/context=None).
                search_type = "title" if title_only else "text"
+                # Trigger: title_only — the title search exists to find THE note by
+                #          exact title, not to page through suggestions.
+                # Why: paginating it by the caller's page would skip an exact match
+                #      sitting on page 1 (read_note("Exact Title", page=2)), and a
+                #      small caller page_size could let a higher-ranked fuzzy title
+                #      displace the exact match out of the lookup window
+                #      (read_note("Foo Bar", page_size=1) when "Foo Bar Foo Bar"
+                #      ranks first) — both returning suggestions instead of the note.
+                # Outcome: title lookup uses its own lookup_page with a fixed lookup
+                #          size, walked by the caller below; caller page/page_size
+                #          apply only to the text-search suggestion listing.
                response = await search_notes(
                    project=active_project.name,
                    project_id=active_project.external_id,
                    query=identifier_text,
                    search_type=search_type,
+                    page=lookup_page if title_only else page,
+                    page_size=_TITLE_LOOKUP_PAGE_SIZE if title_only else page_size,
                    output_format="json",
                    context=context,
                )
@@ -297,12 +359,24 @@ async def read_note(
                logger.info(f"Direct lookup failed for '{entity_path}': {e}")
                # Continue to fallback methods

-            # Fallback 1: Try title search via API
+            # Fallback 1: Try title search via API, walking fixed-size pages of
+            # title results until an exact match is found or results run out.
+            # A single page is not enough: when more than _TITLE_LOOKUP_PAGE_SIZE
+            # higher-ranked fuzzy titles contain the queried phrase, the exact
+            # title lands on a later page and a one-page lookup would miss it.
            logger.info(f"Search title for: {identifier}")
-            title_results = await _search_candidates(identifier, title_only=True)
-
-            title_candidates = _search_results(title_results)
-            if title_candidates:
+            result: dict[str, object] | None = None
+            for lookup_page in range(1, _TITLE_LOOKUP_MAX_PAGES + 1):
+                title_results = await _search_candidates(
+                    identifier, title_only=True, lookup_page=lookup_page
+                )
+                title_candidates = _search_results(title_results)
+                if not title_candidates:
+                    logger.info(
+                        f"No results in title search for: {identifier} "
+                        f"in project {active_project.name}"
+                    )
+                    break
                # Trigger: direct resolution failed and title search returned candidates.
                # Why: avoid returning unrelated notes when search yields only fuzzy matches.
                # Outcome: fetch content only when a true exact title match exists.
@@ -314,33 +388,37 @@ async def read_note(
                    ),
                    None,
                )
-                if not result:
+                if result is not None:
+                    break
+                # Trigger: this page held only fuzzy titles and the server reports
+                #          no further pages (has_more is False or absent).
+                # Why: continuing past the last page would issue empty lookups.
+                # Outcome: give up on the title fallback and try text search below.
+                if title_results.get("has_more") is not True:
                    logger.info(f"No exact title match found for: {identifier}")
-                elif _result_permalink(result):
-                    try:
-                        # Resolve the permalink to entity ID
-                        entity_id = await knowledge_client.resolve_entity(
-                            _result_permalink(result) or "", strict=True
-                        )
+                    break

-                        # Fetch content using the entity ID
-                        response = await resource_client.read(entity_id)
+            if result is not None and _result_permalink(result):
+                try:
+                    # Resolve the permalink to entity ID
+                    entity_id = await knowledge_client.resolve_entity(
+                        _result_permalink(result) or "", strict=True
+                    )

-                        if response.status_code == 200:
-                            logger.info(
-                                f"Found note by exact title search: {_result_permalink(result)}"
-                            )
-                            if output_format == "json":
-                                return await _read_json_payload(entity_id)
-                            return response.text
-                    except Exception as e:  # pragma: no cover
+                    # Fetch content using the entity ID
+                    response = await resource_client.read(entity_id)
+
+                    if response.status_code == 200:
                        logger.info(
-                            f"Failed to fetch content for found title match {_result_permalink(result)}: {e}"
+                            f"Found note by exact title search: {_result_permalink(result)}"
                        )
-            else:
-                logger.info(
-                    f"No results in title search for: {identifier} in project {active_project.name}"
-                )
+                        if output_format == "json":
+                            return await _read_json_payload(entity_id)
+                        return response.text
+                except Exception as e:  # pragma: no cover
+                    logger.info(
+                        f"Failed to fetch content for found title match {_result_permalink(result)}: {e}"
+                    )

            # Fallback 2: Text search as a last resort
            logger.info(f"Title search failed, trying text search for: {identifier}")
@@ -352,6 +430,9 @@ async def read_note(
                if output_format == "json":
                    return _empty_json_payload()
                return format_not_found_message(active_project.name, identifier)
+            # The fallback search is paginated server-side to page_size, so list
+            # the whole returned page instead of a hardcoded cap — otherwise the
+            # caller's page_size would be silently ignored past the cap.
            if output_format == "json":
                payload = _empty_json_payload()
                payload["related_results"] = [
@@ -360,10 +441,10 @@ async def read_note(
                        "permalink": _result_permalink(result),
                        "file_path": _result_file_path(result),
                    }
-                    for result in text_candidates[:5]
+                    for result in text_candidates
                ]
                return payload
-            return format_related_results(active_project.name, identifier, text_candidates[:5])
+            return format_related_results(active_project.name, identifier, text_candidates)


 def format_not_found_message(project: str | None, identifier: str) -> str:
@@ -11,7 +11,7 @@ from fastmcp import Context
 from pydantic import AliasChoices, BeforeValidator, Field

 from basic_memory.config import ConfigManager, has_cloud_credentials
-from basic_memory.utils import build_canonical_permalink, coerce_dict, coerce_list
+from basic_memory.utils import build_canonical_permalink, coerce_dict, coerce_list, parse_tags
 from basic_memory.mcp.async_client import (
    _explicit_routing,
    _force_local_mode,
@@ -676,9 +676,13 @@ async def search_notes(
        Dict[str, Any] | None,
        BeforeValidator(coerce_dict),
    ] = None,
+    # parse_tags, not coerce_list: tags="a,b" must split into ["a", "b"] to match the
+    # tag: query shorthand below and write_note's documented tags convention (#910).
+    # coerce_list would wrap the comma string as the single literal tag ["a,b"],
+    # which matches nothing.
    tags: Annotated[
        List[str] | None,
-        BeforeValidator(coerce_list),
+        BeforeValidator(parse_tags),
    ] = None,
    status: Optional[str] = None,
    min_similarity: Annotated[
@@ -795,7 +799,9 @@ async def search_notes(
                   observations whose category matches exactly.
        after_date: Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01")
        metadata_filters: Optional structured frontmatter filters (e.g., {"status": "in-progress"})
-        tags: Optional tag filter (frontmatter tags); shorthand for metadata_filters["tags"]
+        tags: Optional tag filter (frontmatter tags); shorthand for metadata_filters["tags"].
+              Accepts a list (["a", "b"]) or a comma-separated string ("a,b"), matching the
+              write_note tags convention and the tag: query shorthand.
        status: Optional status filter (frontmatter status); shorthand for metadata_filters["status"]
        min_similarity: Optional float to override the global semantic_min_similarity threshold
                       for this query. E.g., 0.0 to see all vector results, or 0.8 for high precision.
@@ -87,8 +87,12 @@ async def write_note(
                   Use forward slashes (/) as separators. Use "/" or "" to write to project root.
                   Examples: "notes", "projects/2025", "research/ml", "/" (root)
        project: Project name to write to. Optional - server will resolve using the
-                hierarchy above. If unknown, use list_memory_projects() to discover
-                available projects.
+                hierarchy above. Use "workspace/project" to route to a project in a
+                specific cloud workspace. A bare name that exists in multiple
+                workspaces resolves to the default workspace, so use the qualified
+                form (or project_id) to disambiguate. If unknown, use
+                list_memory_projects() to discover available projects and their
+                qualified names.
        project_id: Project external_id (UUID). Prefer this over `project` when known —
                it routes to the exact project regardless of name collisions across cloud
                workspaces. Takes precedence over `project`. Get from list_memory_projects().
@@ -1,5 +1,6 @@
 """Knowledge graph models."""

+import hashlib
 import uuid
 from datetime import datetime
 from basic_memory.utils import ensure_timezone_aware
@@ -252,8 +253,18 @@ class Observation(Base):
        Content is truncated to 200 chars to stay under PostgreSQL's
        btree index limit of 2704 bytes.
        """
-        # Truncate content to avoid exceeding PostgreSQL's btree index limit
-        content_for_permalink = self.content[:200] if len(self.content) > 200 else self.content
+        if len(self.content) > 200:
+            # Trigger: content exceeds the 200-char budget imposed by PostgreSQL's
+            # 2704-byte btree index row limit, so the permalink can only carry a prefix.
+            # Why: two distinct observations with the same category and an identical
+            # 200-char prefix would collide on the same synthetic permalink, and the
+            # search index (permalink-keyed upsert) silently drops the second one.
+            # Outcome: a short stable digest of the FULL content disambiguates
+            # truncated permalinks while staying well under the index limit.
+            digest = hashlib.sha256(self.content.encode("utf-8")).hexdigest()[:12]
+            content_for_permalink = f"{self.content[:200]}-{digest}"
+        else:
+            content_for_permalink = self.content
        return generate_permalink(
            f"{self.entity.permalink}/observations/{self.category}/{content_for_permalink}"
        )
@@ -381,6 +381,13 @@ def app_config(
        sync_changes=False,  # Disable file sync in tests - prevents lifespan from starting blocking task
        database_backend=database_backend,
        database_url=database_url,
+        # Trigger: semantic_search_enabled defaults to True whenever fastembed/sqlite-vec
+        #          are importable, which they are in dev and CI environments.
+        # Why: with it on, every test that syncs pays the ONNX embedding stack (~5-7s per
+        #      sync) — embeddings are covered by test-int/semantic/, which configures
+        #      semantic_search_enabled explicitly in its own conftest.
+        # Outcome: non-semantic integration tests skip embedding work entirely.
+        semantic_search_enabled=False,
    )
    return app_config

@@ -13,9 +13,49 @@ import pytest
 from fastmcp import Client


-# --- read_note: pagination params removed in #693 (were no-ops) ---
-# The `page` / `page_size` parameters were removed because the API endpoint
-# silently dropped them. Search-fallback pagination is unrelated to read_note.
+# --- read_note: pagination params restored in #883 ---
+# `page` / `page_size` were removed in #693 because they were no-ops on the
+# resource read. #883 restored them for parity with the sibling navigation
+# tools: they paginate the server-side search fallback (a direct match still
+# returns the full note content).
+
+
+@pytest.mark.asyncio
+async def test_read_note_accepts_pagination_params_and_aliases(mcp_server, app, test_project):
+    """Agents passing page/page_size (or their aliases) must not get a validation error."""
+    async with Client(mcp_server) as client:
+        await client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Paged Read Note",
+                "directory": "test",
+                "content": "# Paged Read Note\n\npaged read body",
+            },
+        )
+
+        result = await client.call_tool(
+            "read_note",
+            {
+                "project": test_project.name,
+                "identifier": "Paged Read Note",
+                "page": 1,
+                "page_size": 10,
+            },
+        )
+        assert "paged read body" in result.content[0].text
+
+        # Aliases map silently: page_number -> page, limit -> page_size
+        result = await client.call_tool(
+            "read_note",
+            {
+                "project": test_project.name,
+                "identifier": "Paged Read Note",
+                "page_number": 1,
+                "limit": 10,
+            },
+        )
+        assert "paged read body" in result.content[0].text


 # --- edit_note: find_text / content / section aliases ---
@@ -485,12 +525,12 @@ async def test_aliases_not_advertised_in_schema(mcp_server, app):

        # tool_name -> (must_have_canonical, must_not_have_aliases)
        checks = {
-            # read_note has no pagination params (#693 — they were no-ops; removed).
-            # The must_not_have list still includes the rejected aliases so future
-            # contributors don't reintroduce them.
+            # read_note pagination restored in #883 (paginates the search fallback).
+            # Accepted aliases (limit/page_number/per_page) plus the rejected
+            # `offset` must stay out of the advertised schema.
            "read_note": (
-                [],
-                ["page", "page_size", "offset", "limit", "page_number", "per_page"],
+                ["page", "page_size"],
+                ["offset", "limit", "page_number", "per_page"],
            ),
            "edit_note": (
                ["find_text", "section", "content"],
@@ -17,12 +17,13 @@ this path.

 import os
 import sqlite3
+from unittest.mock import patch

 import pytest
 from sqlalchemy import text

 from basic_memory import db
-from basic_memory.config import BasicMemoryConfig, DatabaseBackend
+from basic_memory.config import BasicMemoryConfig, ConfigManager, DatabaseBackend
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.project_repository import ProjectRepository
 from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
@@ -153,7 +154,19 @@ async def test_embedding_status_reads_real_vec0_table(engine_factory, test_proje
    project_repository = ProjectRepository(session_maker)
    project_service = ProjectService(project_repository)

-    status = await project_service.get_embedding_status(project_id)
+    # Test fixtures run with semantic search disabled; the status call reads the global
+    # ConfigManager, so patch it to report semantic enabled for this regression path.
+    def _config_manager_semantic_enabled() -> ConfigManager:
+        cm = ConfigManager()
+        cm.config.semantic_search_enabled = True
+        return cm
+
+    with patch.object(
+        type(project_service),
+        "config_manager",
+        new_callable=lambda: property(lambda self: _config_manager_semantic_enabled()),
+    ):
+        status = await project_service.get_embedding_status(project_id)

    assert status.semantic_search_enabled is True
    # The vec0 JOIN must succeed, so the table is reported as present and healthy.
@@ -0,0 +1,138 @@
+import re
+from pathlib import Path
+
+import yaml
+
+
+WORKFLOW_PATH = Path(".github/workflows/bm-bossbot.yml")
+
+
+def _workflow() -> dict:
+    return yaml.safe_load(WORKFLOW_PATH.read_text(encoding="utf-8"))
+
+
+def test_bm_bossbot_runs_after_successful_tests_workflow() -> None:
+    workflow = _workflow()
+    review_job = workflow["jobs"]["review"]
+
+    assert workflow["name"] == "BM Bossbot"
+    assert "pull_request_target" not in workflow["on"]
+    assert workflow["on"]["workflow_run"]["workflows"] == ["Tests"]
+    assert workflow["on"]["workflow_run"]["types"] == ["completed"]
+    assert "workflow_dispatch" in workflow["on"]
+    assert "github.event.workflow_run.conclusion == 'success'" in review_job["if"]
+    assert "github.event.workflow_run.pull_requests[0].number != ''" in review_job["if"]
+    assert review_job["outputs"]["should_review"] == "${{ steps.pr.outputs.should_review }}"
+
+    permissions = workflow["permissions"]
+    assert permissions["contents"] == "read"
+    assert permissions["pull-requests"] == "write"
+    assert permissions["statuses"] == "write"
+
+    assert "assets" not in workflow["jobs"]
+
+
+def test_bm_bossbot_workflow_never_checks_out_untrusted_head() -> None:
+    workflow = _workflow()
+    checkout_steps = [
+        step
+        for job in workflow["jobs"].values()
+        for step in job["steps"]
+        if step.get("uses") == "actions/checkout@v6"
+    ]
+
+    assert checkout_steps
+    for checkout_step in checkout_steps:
+        assert checkout_step["with"]["ref"] == "${{ github.event.repository.default_branch }}"
+        assert "${{ github.event.pull_request.head.sha }}" not in str(checkout_step)
+    workflow_text = WORKFLOW_PATH.read_text(encoding="utf-8")
+    # The danger is consuming UNTRUSTED PR data: checking out the PR head, or
+    # interpolating attacker-controlled strings (title/body/branch names) into
+    # run scripts. The numeric PR id is safe and the recheck job needs it, so
+    # allow exactly `.number` and nothing else from the pull_request payload.
+    pr_event_fields = set(re.findall(r"github\.event\.pull_request\.[a-zA-Z_.]+", workflow_text))
+    assert pr_event_fields <= {"github.event.pull_request.number"}
+    assert "github.event.pull_request.head" not in workflow_text
+    assert "cancel-in-progress: true" in workflow_text
+
+
+def test_bm_bossbot_workflow_has_deterministic_status_steps() -> None:
+    workflow = _workflow()
+    steps = workflow["jobs"]["review"]["steps"]
+    names = [step["name"] for step in steps]
+
+    assert "Set up uv" in names
+    assert "Mark BM Bossbot approval pending" in names
+    assert "Finalize BM Bossbot approval" in names
+    # The gate is deterministic: no LLM review step and no image generation.
+    assert "Run BM Bossbot review with Codex" not in names
+    assert "Collect sanitized PR context" not in names
+
+    workflow_text = WORKFLOW_PATH.read_text(encoding="utf-8")
+    assert "openai/codex-action" not in workflow_text
+    assert "OPENAI_API_KEY" not in workflow_text
+
+    pending = next(step for step in steps if step["name"] == "Mark BM Bossbot approval pending")
+    assert pending["if"] == "steps.pr.outputs.should_review == 'true'"
+    finalize = next(step for step in steps if step["name"] == "Finalize BM Bossbot approval")
+    assert finalize["if"] == "always() && steps.pr.outputs.should_review == 'true'"
+    assert '--trusted "${{ steps.trust.outputs.trusted_author }}"' in finalize["run"]
+    assert "BM Bossbot Approval" in workflow_text
+    assert "uv run --script scripts/bm_bossbot_status.py pending" in workflow_text
+    assert "uv run --script scripts/bm_bossbot_status.py finalize" in workflow_text
+
+
+def test_bm_bossbot_rejects_stale_successful_test_runs_before_finalize() -> None:
+    workflow_text = WORKFLOW_PATH.read_text(encoding="utf-8")
+    workflow = _workflow()
+    steps = workflow["jobs"]["review"]["steps"]
+    normalize = next(step for step in steps if step["name"] == "Normalize PR event")
+    classify = next(step for step in steps if step["name"] == "Classify PR author")
+
+    assert "tested_sha" in normalize["run"]
+    assert "current_head_sha" in normalize["run"]
+    assert "actions/workflows/test.yml/runs" in normalize["run"]
+    assert "-f event=push" in normalize["run"]
+    assert "-f event=pull_request" not in normalize["run"]
+    assert '-f head_sha="${current_head_sha}"' in normalize["run"]
+    assert 'select(.conclusion == "success")' in normalize["run"]
+    assert "no successful Tests workflow for ${current_head_sha}" in workflow_text
+    stale_sha_guard = '[ -n "${tested_sha}" ] && [ "${tested_sha}" != "${current_head_sha}" ]'
+    assert stale_sha_guard in normalize["run"]
+    assert "should_review=false" in normalize["run"]
+    assert (
+        "Tests passed for ${tested_sha}, but current head is ${current_head_sha}" in workflow_text
+    )
+    assert classify["if"] == "steps.pr.outputs.should_review == 'true'"
+
+
+def test_bm_bossbot_has_no_image_generation() -> None:
+    """The per-PR image job was removed: it spent OpenAI tokens on every run."""
+    workflow = _workflow()
+    workflow_text = WORKFLOW_PATH.read_text(encoding="utf-8")
+
+    assert "assets" not in workflow["jobs"]
+    assert "generate_pr_infographic" not in workflow_text
+    assert "pr-assets/" not in workflow_text
+
+
+def test_bm_bossbot_classifies_authors_and_gates_untrusted_deterministically() -> None:
+    workflow = _workflow()
+    steps = workflow["jobs"]["review"]["steps"]
+
+    classify = next(step for step in steps if step["name"] == "Classify PR author")
+    finalize = next(step for step in steps if step["name"] == "Finalize BM Bossbot approval")
+
+    assert "OWNER|MEMBER|COLLABORATOR" in classify["run"]
+    assert classify["if"] == "steps.pr.outputs.should_review == 'true'"
+    assert '--trusted "${{ steps.trust.outputs.trusted_author }}"' in finalize["run"]
+
+
+def test_claude_code_review_is_manual_advisory_only() -> None:
+    workflow = yaml.safe_load(
+        Path(".github/workflows/claude-code-review.yml").read_text(encoding="utf-8")
+    )
+
+    assert "pull_request" not in workflow["on"]
+    assert "workflow_dispatch" in workflow["on"]
+    assert workflow["on"]["workflow_dispatch"]["inputs"]["pr_number"]["required"] is True
@@ -0,0 +1,114 @@
+from pathlib import Path
+
+import pytest
+
+from scripts import testmon_cache
+
+
+def _write_testmon_file(directory: Path, filename: str, content: str) -> Path:
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / filename
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def test_seed_testmon_data_reports_missing_shared_cache(tmp_path: Path) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    repo_root.mkdir()
+
+    result = testmon_cache.seed_testmon_data(repo_root=repo_root, cache_dir=cache_dir)
+
+    assert result.status == "missing"
+    assert result.copied == ()
+    assert not (repo_root / ".testmondata").exists()
+
+
+def test_seed_testmon_data_keeps_existing_local_data(tmp_path: Path) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    local_datafile = _write_testmon_file(repo_root, ".testmondata", "local")
+    _write_testmon_file(cache_dir, ".testmondata", "shared")
+
+    result = testmon_cache.seed_testmon_data(repo_root=repo_root, cache_dir=cache_dir)
+
+    assert result.status == "exists"
+    assert result.copied == ()
+    assert local_datafile.read_text(encoding="utf-8") == "local"
+
+
+def test_seed_testmon_data_replaces_stale_sidecars(tmp_path: Path) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    _write_testmon_file(repo_root, ".testmondata-shm", "stale sidecar")
+    _write_testmon_file(cache_dir, ".testmondata", "shared main")
+    _write_testmon_file(cache_dir, ".testmondata-wal", "shared wal")
+
+    result = testmon_cache.seed_testmon_data(repo_root=repo_root, cache_dir=cache_dir)
+
+    assert result.status == "seeded"
+    assert {path.name for path in result.copied} == {".testmondata", ".testmondata-wal"}
+    assert (repo_root / ".testmondata").read_text(encoding="utf-8") == "shared main"
+    assert (repo_root / ".testmondata-wal").read_text(encoding="utf-8") == "shared wal"
+    assert not (repo_root / ".testmondata-shm").exists()
+
+
+def test_refresh_testmon_data_requires_local_data(tmp_path: Path) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    repo_root.mkdir()
+
+    with pytest.raises(FileNotFoundError):
+        testmon_cache.refresh_testmon_data(repo_root=repo_root, cache_dir=cache_dir)
+
+
+def test_refresh_testmon_data_replaces_shared_cache(tmp_path: Path) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    _write_testmon_file(repo_root, ".testmondata", "local main")
+    _write_testmon_file(repo_root, ".testmondata-shm", "local shm")
+    _write_testmon_file(cache_dir, ".testmondata", "old main")
+    _write_testmon_file(cache_dir, ".testmondata-wal", "old wal")
+
+    result = testmon_cache.refresh_testmon_data(repo_root=repo_root, cache_dir=cache_dir)
+
+    assert result.status == "refreshed"
+    assert {path.name for path in result.copied} == {".testmondata", ".testmondata-shm"}
+    assert (cache_dir / ".testmondata").read_text(encoding="utf-8") == "local main"
+    assert (cache_dir / ".testmondata-shm").read_text(encoding="utf-8") == "local shm"
+    assert not (cache_dir / ".testmondata-wal").exists()
+
+
+def test_resolve_cache_dir_prefers_explicit_path_over_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    repo_root = tmp_path / "repo"
+    env_cache_dir = tmp_path / "env-cache"
+    explicit_cache_dir = tmp_path / "explicit-cache"
+    repo_root.mkdir()
+    monkeypatch.setenv(testmon_cache.TESTMON_CACHE_ENV, str(env_cache_dir))
+
+    assert testmon_cache.resolve_cache_dir(repo_root) == env_cache_dir.resolve()
+    assert (
+        testmon_cache.resolve_cache_dir(repo_root, explicit_cache_dir)
+        == explicit_cache_dir.resolve()
+    )
+
+
+def test_status_command_prints_local_and_shared_paths(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    repo_root = tmp_path / "repo"
+    cache_dir = tmp_path / "cache"
+    repo_root.mkdir()
+    _write_testmon_file(repo_root, ".testmondata", "local main")
+
+    exit_code = testmon_cache.main(
+        ["--repo-root", str(repo_root), "--cache-dir", str(cache_dir), "status"]
+    )
+
+    assert exit_code == 0
+    output = capsys.readouterr().out
+    assert f"Repo root:      {repo_root.resolve()}" in output
+    assert "Worktree ready: True" in output
+    assert "Cache ready:    False" in output
@@ -8,6 +8,7 @@ import typer
 from typer.testing import CliRunner

 from basic_memory.cli.app import app
+from basic_memory.cli.commands.cloud.rclone_commands import TransferPlan
 from basic_memory.config import ProjectEntry, ProjectMode
 from basic_memory.schemas.cloud import WorkspaceInfo

@@ -34,7 +35,7 @@ def test_cloud_sync_commands_skip_explicit_cloud_project_sync(monkeypatch, argv,

    monkeypatch.setattr(project_sync_command, "_require_cloud_credentials", lambda _config: None)
    monkeypatch.setattr(
-        project_sync_command, "_require_personal_workspace", lambda _name, _config: None
+        project_sync_command, "_require_personal_workspace", lambda _name, _config, **_kwargs: None
    )
    monkeypatch.setattr(
        project_sync_command,
@@ -72,7 +73,7 @@ def test_cloud_bisync_fails_fast_when_sync_entry_disappears(monkeypatch, config_

    monkeypatch.setattr(project_sync_command, "_require_cloud_credentials", lambda _config: None)
    monkeypatch.setattr(
-        project_sync_command, "_require_personal_workspace", lambda _name, _config: None
+        project_sync_command, "_require_personal_workspace", lambda _name, _config, **_kwargs: None
    )
    monkeypatch.setattr(
        project_sync_command,
@@ -141,11 +142,12 @@ def test_cloud_bisync_commands_block_organization_workspace(monkeypatch, argv, c
    assert result.exit_code == 1, result.output
    output = " ".join(result.output.split())
    assert "The bisync operation is only supported on Personal workspaces" in output
-    assert "Use `bm cloud sync --name research` instead" in output
+    assert "bm cloud pull --name research" in output
+    assert "bm cloud push --name research" in output


-def test_cloud_sync_allows_organization_workspace(monkeypatch, config_manager):
-    """Team workspaces can still use the one-way sync command."""
+def test_cloud_sync_blocks_organization_workspace(monkeypatch, config_manager):
+    """The destructive mirror `sync` is now Personal-only and blocks Team workspaces."""
    project_sync_command = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")

    config = config_manager.load_config()
@@ -161,7 +163,41 @@ def test_cloud_sync_allows_organization_workspace(monkeypatch, config_manager):
    monkeypatch.setattr(
        project_sync_command,
        "get_available_workspaces",
-        lambda: pytest.fail("sync should not require a personal workspace"),
+        lambda: _async_value([_workspace("team-tenant", "organization", "team")]),
+    )
+    monkeypatch.setattr(
+        project_sync_command,
+        "get_mount_info",
+        lambda: pytest.fail("workspace guard should run before mount lookup"),
+    )
+
+    result = runner.invoke(app, ["cloud", "sync", "--name", "research"])
+
+    assert result.exit_code == 1, result.output
+    output = " ".join(result.output.split())
+    assert "only supported on Personal workspaces" in output
+    assert "bm cloud push --name research" in output
+    assert "bm cloud pull --name research" in output
+
+
+def test_cloud_sync_allows_personal_workspace(monkeypatch, config_manager):
+    """Personal workspaces keep the one-way mirror sync available."""
+    project_sync_command = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+
+    config = config_manager.load_config()
+    config.cloud_api_key = "bmc_test"
+    config.projects["research"] = ProjectEntry(
+        path="/tmp/research",
+        mode=ProjectMode.CLOUD,
+        workspace_id="personal-tenant",
+        local_sync_path="/tmp/research",
+    )
+    config_manager.save_config(config)
+
+    monkeypatch.setattr(
+        project_sync_command,
+        "get_available_workspaces",
+        lambda: _async_value([_workspace("personal-tenant", "personal", "personal")]),
    )
    monkeypatch.setattr(
        project_sync_command,
@@ -351,6 +387,334 @@ def test_bisync_reset_skips_workspace_check_without_credentials(monkeypatch, tmp
    assert "No bisync state found for project 'research'" in result.output


+def _stub_transfer_env(
+    monkeypatch, module, *, plan, transfer_result=True, recorder=None, workspace=None
+):
+    """Stub the push/pull dependency chain so only diff/transfer logic is exercised."""
+    monkeypatch.setattr(module, "_require_cloud_credentials", lambda _config: None)
+    ws = workspace or _workspace("personal-tenant", "personal", "personal", is_default=True)
+    monkeypatch.setattr(
+        module,
+        "_get_workspace_for_project",
+        lambda _name, _config, **_kwargs: _async_value(ws),
+    )
+    monkeypatch.setattr(module, "rclone_remote_exists", lambda _remote: True)
+    monkeypatch.setattr(
+        module,
+        "get_mount_info",
+        lambda **_kwargs: _async_value(
+            SimpleNamespace(bucket_name="tenant-bucket", tenant_id=ws.tenant_id)
+        ),
+    )
+    monkeypatch.setattr(
+        module,
+        "_get_cloud_project",
+        lambda _name, **_kwargs: _async_value(SimpleNamespace(name="research", path="research")),
+    )
+    monkeypatch.setattr(
+        module,
+        "_get_sync_project",
+        lambda _name, _config, _project_data, **kwargs: (
+            SimpleNamespace(name="research", remote_name=kwargs.get("remote_name")),
+            "/tmp/research",
+        ),
+    )
+    monkeypatch.setattr(module, "project_diff", lambda *args, **kwargs: plan)
+
+    def _fake_transfer(*args, **kwargs):
+        if recorder is not None:
+            recorder["args"] = args
+            recorder["kwargs"] = kwargs
+        return transfer_result
+
+    monkeypatch.setattr(module, "project_transfer", _fake_transfer)
+
+
+def test_cloud_pull_aborts_on_conflict_by_default(monkeypatch, config_manager):
+    """Pull refuses to clobber: it lists conflicts and exits without transferring."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=["new.md"], conflicts=["notes/dup.md"], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "pull", "--name", "research"])
+
+    assert result.exit_code == 1, result.output
+    output = " ".join(result.output.split())
+    assert "notes/dup.md" in output
+    assert "--on-conflict keep-cloud" in output
+    assert "args" not in recorder  # transfer never ran
+
+
+def test_cloud_pull_clean_transfers(monkeypatch, config_manager):
+    """With no conflicts, pull proceeds and reports success."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=["new.md"], conflicts=[], dest_only=["local-only.md"], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "pull", "--name", "research"])
+
+    assert result.exit_code == 0, result.output
+    output = " ".join(result.output.lower().split())
+    assert "research pull completed successfully" in output
+    # Deletions are surfaced, not propagated
+    assert "deletions are not propagated" in output
+    assert recorder["kwargs"]["strategy"] == "fail"
+    assert recorder["args"][2] == "pull"
+
+
+def test_cloud_pull_keep_cloud_resolves_conflict(monkeypatch, config_manager):
+    """An explicit --on-conflict strategy lets pull proceed through conflicts."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=[], conflicts=["notes/dup.md"], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(
+        app, ["cloud", "pull", "--name", "research", "--on-conflict", "keep-cloud"]
+    )
+
+    assert result.exit_code == 0, result.output
+    assert recorder["kwargs"]["strategy"] == "keep-cloud"
+
+
+def test_cloud_pull_aborts_on_compare_errors(monkeypatch, config_manager):
+    """If rclone cannot read/hash files, pull aborts before transferring."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=[], conflicts=[], dest_only=[], errors=["bad.md"])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "pull", "--name", "research"])
+
+    assert result.exit_code == 1, result.output
+    assert "could not compare" in result.output
+    assert "args" not in recorder  # transfer never ran
+
+
+def test_cloud_push_aborts_on_conflict_by_default(monkeypatch, config_manager):
+    """Push aborts on conflicts like a rejected git push (pull first)."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=["new.md"], conflicts=["notes/dup.md"], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "push", "--name", "research"])
+
+    assert result.exit_code == 1, result.output
+    assert "notes/dup.md" in result.output
+    assert "args" not in recorder
+
+
+def test_cloud_push_keep_local_resolves_conflict(monkeypatch, config_manager):
+    """Push with --on-conflict keep-local overwrites cloud and reports the direction."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    plan = TransferPlan(new=[], conflicts=["notes/dup.md"], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder)
+
+    result = runner.invoke(
+        app, ["cloud", "push", "--name", "research", "--on-conflict", "keep-local"]
+    )
+
+    assert result.exit_code == 0, result.output
+    assert recorder["kwargs"]["strategy"] == "keep-local"
+    assert recorder["args"][2] == "push"
+
+
+def test_cloud_push_allows_organization_workspace(monkeypatch, config_manager):
+    """push is additive and Team-safe — an organization workspace is allowed (no Personal gate)."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+
+    org_ws = _workspace("team-tenant", "organization", "acme", is_default=False)
+    plan = TransferPlan(new=["new.md"], conflicts=[], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder, workspace=org_ws)
+
+    result = runner.invoke(app, ["cloud", "push", "--name", "research"])
+
+    assert result.exit_code == 0, result.output
+    assert "research push completed successfully" in result.output
+    # Routed through the team workspace's own remote, against its tenant's bucket.
+    assert recorder["args"][0].remote_name == "basic-memory-cloud-acme"
+
+
+def test_cloud_pull_workspace_override_routes_through_workspace_remote(monkeypatch, config_manager):
+    """pull --workspace routes through the named workspace's own remote and bucket."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+
+    org_ws = _workspace("team-tenant", "organization", "acme", is_default=False)
+    plan = TransferPlan(new=["new.md"], conflicts=[], dest_only=[], errors=[])
+    recorder: dict = {}
+
+    # _get_workspace_for_project must receive the override and return the org workspace.
+    def _resolve(_name, _config, *, workspace_override=None):
+        assert workspace_override == "acme"
+        return _async_value(org_ws)
+
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder, workspace=org_ws)
+    monkeypatch.setattr(module, "_get_workspace_for_project", _resolve)
+
+    result = runner.invoke(app, ["cloud", "pull", "--name", "research", "--workspace", "acme"])
+
+    assert result.exit_code == 0, result.output
+    assert recorder["args"][0].remote_name == "basic-memory-cloud-acme"
+    assert recorder["args"][2] == "pull"
+
+
+def test_cloud_push_errors_when_workspace_remote_not_set_up(monkeypatch, config_manager):
+    """If the workspace's remote isn't configured, push stops with the setup command."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+
+    org_ws = _workspace("team-tenant", "organization", "acme", is_default=False)
+    plan = TransferPlan(new=["new.md"], conflicts=[], dest_only=[], errors=[])
+    recorder: dict = {}
+    _stub_transfer_env(monkeypatch, module, plan=plan, recorder=recorder, workspace=org_ws)
+    # Override: this workspace has not been set up yet.
+    monkeypatch.setattr(module, "rclone_remote_exists", lambda _remote: False)
+
+    result = runner.invoke(app, ["cloud", "push", "--name", "research"])
+
+    assert result.exit_code == 1, result.output
+    output = " ".join(result.output.split())
+    assert "not set up for sync" in output
+    assert "bm cloud setup --workspace acme" in output
+    assert "args" not in recorder  # never transferred
+
+
+def test_get_workspace_for_project_override_resolves(monkeypatch, config_manager):
+    """An explicit --workspace override selects that workspace regardless of config."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    config = config_manager.load_config()
+    monkeypatch.setattr(
+        module,
+        "get_available_workspaces",
+        lambda: _async_value(
+            [
+                _workspace("personal-tenant", "personal", "personal", is_default=True),
+                _workspace("team-tenant", "organization", "acme"),
+            ]
+        ),
+    )
+
+    ws = module.run_with_cleanup(
+        module._get_workspace_for_project("research", config, workspace_override="acme")
+    )
+
+    assert ws.tenant_id == "team-tenant"
+
+
+def test_get_workspace_for_project_override_no_match_raises(monkeypatch, config_manager):
+    """An override that matches no accessible workspace is a clear error."""
+    module = importlib.import_module("basic_memory.cli.commands.cloud.project_sync")
+    config = config_manager.load_config()
+    monkeypatch.setattr(
+        module,
+        "get_available_workspaces",
+        lambda: _async_value(
+            [_workspace("personal-tenant", "personal", "personal", is_default=True)]
+        ),
+    )
+
+    with pytest.raises(ValueError) as exc_info:
+        module.run_with_cleanup(
+            module._get_workspace_for_project("research", config, workspace_override="acme")
+        )
+
+    assert "No accessible workspace matches 'acme'" in str(exc_info.value)
+
+
+def _stub_setup_env(monkeypatch, core, *, remote_exists=False, recorder=None):
+    """Stub the `bm cloud setup` dependency chain for the acme workspace."""
+    monkeypatch.setattr(core, "install_rclone", lambda: None)
+    monkeypatch.setattr(
+        core,
+        "get_available_workspaces",
+        lambda: _async_value([_workspace("team-tenant", "organization", "acme")]),
+    )
+    monkeypatch.setattr(core, "rclone_remote_exists", lambda _remote: remote_exists)
+
+    def _mint(_tenant_id):
+        if recorder is not None:
+            recorder["minted"] = True
+        return _async_value(SimpleNamespace(access_key="ak", secret_key="sk"))
+
+    monkeypatch.setattr(
+        core,
+        "get_mount_info",
+        lambda **_kwargs: _async_value(
+            SimpleNamespace(tenant_id="team-tenant", bucket_name="acme-bucket")
+        ),
+    )
+    monkeypatch.setattr(core, "generate_mount_credentials", _mint)
+
+    def _fake_configure(**kwargs):
+        if recorder is not None:
+            recorder.update(kwargs)
+        return kwargs.get("remote_name")
+
+    monkeypatch.setattr(core, "configure_rclone_remote", _fake_configure)
+
+
+def test_cloud_setup_workspace_configures_named_remote(monkeypatch):
+    """`bm cloud setup --workspace acme` provisions the acme tenant's own remote."""
+    core = importlib.import_module("basic_memory.cli.commands.cloud.core_commands")
+    recorder: dict = {}
+    _stub_setup_env(monkeypatch, core, remote_exists=False, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "setup", "--workspace", "acme"])
+
+    assert result.exit_code == 0, result.output
+    assert recorder["remote_name"] == "basic-memory-cloud-acme"
+
+
+def test_cloud_setup_aborts_when_remote_exists_without_force(monkeypatch):
+    """Setup refuses to overwrite an existing remote, and mints nothing (the #922 footgun)."""
+    core = importlib.import_module("basic_memory.cli.commands.cloud.core_commands")
+    recorder: dict = {}
+    _stub_setup_env(monkeypatch, core, remote_exists=True, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "setup", "--workspace", "acme"])
+
+    assert result.exit_code == 1, result.output
+    output = " ".join(result.output.split())
+    assert "basic-memory-cloud-acme' is already configured" in output
+    assert "--force" in output
+    # Aborted before minting credentials or touching the remote.
+    assert "minted" not in recorder
+    assert "remote_name" not in recorder
+
+
+def test_cloud_setup_force_overwrites_existing_remote(monkeypatch):
+    """--force reconfigures an existing remote."""
+    core = importlib.import_module("basic_memory.cli.commands.cloud.core_commands")
+    recorder: dict = {}
+    _stub_setup_env(monkeypatch, core, remote_exists=True, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "setup", "--workspace", "acme", "--force"])
+
+    assert result.exit_code == 0, result.output
+    assert recorder["remote_name"] == "basic-memory-cloud-acme"
+    assert recorder.get("minted") is True
+
+
+def test_cloud_setup_default_workspace_aborts_when_remote_exists(monkeypatch):
+    """The original footgun: `bm cloud setup` (no --workspace) must not clobber
+    the shared basic-memory-cloud remote without --force."""
+    core = importlib.import_module("basic_memory.cli.commands.cloud.core_commands")
+    recorder: dict = {}
+    _stub_setup_env(monkeypatch, core, remote_exists=True, recorder=recorder)
+
+    result = runner.invoke(app, ["cloud", "setup"])  # no --workspace → basic-memory-cloud
+
+    assert result.exit_code == 1, result.output
+    output = " ".join(result.output.split())
+    assert "'basic-memory-cloud' is already configured" in output
+    assert "minted" not in recorder  # nothing minted on abort
+    assert "remote_name" not in recorder
+
+
 async def _async_value(value):
    return value

@@ -1,9 +1,14 @@
 import time

+import pytest
+
 from basic_memory.cli.commands.cloud.bisync_commands import convert_bmignore_to_rclone_filters
 from basic_memory.cli.commands.cloud.rclone_config import (
+    RcloneConfigError,
    configure_rclone_remote,
    get_rclone_config_path,
+    rclone_remote_exists,
+    remote_name_for_workspace,
 )
 from basic_memory.ignore_utils import get_bmignore_path

@@ -111,3 +116,36 @@ def test_configure_rclone_remote_writes_config_and_backs_up_existing(config_home
    # Backup exists
    backups = list(cfg_path.parent.glob("rclone.conf.backup-*"))
    assert backups, "expected a backup of rclone.conf to be created"
+
+
+def test_remote_name_for_workspace():
+    # Default workspace keeps the legacy remote name (back-compat)
+    assert remote_name_for_workspace("personal", is_default=True) == "basic-memory-cloud"
+    assert remote_name_for_workspace(None, is_default=False) == "basic-memory-cloud"
+    # Non-default workspaces get their own tenant-scoped remote
+    assert remote_name_for_workspace("acme", is_default=False) == "basic-memory-cloud-acme"
+
+
+def test_remote_name_for_workspace_rejects_unsafe_slug():
+    # A slug from the API with characters invalid in an rclone remote name must
+    # fail fast rather than write a broken rclone.conf section.
+    for bad in ["a/b", "has space", "dot.dot", "weird:name"]:
+        with pytest.raises(RcloneConfigError):
+            remote_name_for_workspace(bad, is_default=False)
+
+
+def test_configure_rclone_remote_named_workspace_remote(config_home):
+    remote = configure_rclone_remote(
+        access_key="ak", secret_key="sk", remote_name="basic-memory-cloud-acme"
+    )
+    assert remote == "basic-memory-cloud-acme"
+
+    text = get_rclone_config_path().read_text(encoding="utf-8")
+    assert "[basic-memory-cloud-acme]" in text
+    assert "access_key_id = ak" in text
+
+
+def test_rclone_remote_exists(config_home):
+    assert rclone_remote_exists("basic-memory-cloud-acme") is False
+    configure_rclone_remote(access_key="ak", secret_key="sk", remote_name="basic-memory-cloud-acme")
+    assert rclone_remote_exists("basic-memory-cloud-acme") is True
@@ -292,6 +292,13 @@ def app_config(config_home, db_backend, postgres_container, monkeypatch) -> Basi
        update_permalinks_on_move=True,
        database_backend=backend,
        database_url=database_url,
+        # Trigger: semantic_search_enabled defaults to True whenever fastembed/sqlite-vec
+        #          are importable, which they are in dev and CI environments.
+        # Why: with it on, every test that syncs pays the ONNX embedding stack (~5-7s per
+        #      sync) — embeddings are covered by the dedicated semantic suites, which
+        #      configure semantic_search_enabled explicitly themselves.
+        # Outcome: non-semantic tests skip embedding work entirely.
+        semantic_search_enabled=False,
    )

    return app_config
@@ -62,6 +62,8 @@ EXPECTED_TOOL_SIGNATURES: dict[str, list[str]] = {
        "identifier",
        "project",
        "project_id",
+        "page",
+        "page_size",
        "output_format",
        "include_frontmatter",
    ],
@@ -120,6 +120,306 @@ async def test_read_note_returns_related_results_when_text_search_finds_matches(
    assert "## 2. Related Two" in result


+@pytest.mark.asyncio
+async def test_read_note_direct_match_returns_full_content_regardless_of_paging(app, test_project):
+    """page/page_size never chunk note content — a direct match returns the whole note."""
+    content = "Line one of the note\nLine two of the note\nLine three of the note"
+    await write_note(
+        project=test_project.name,
+        title="Paging Direct Note",
+        directory="test",
+        content=content,
+    )
+
+    result = await read_note(
+        "test/paging-direct-note",
+        project=test_project.name,
+        page=3,
+        page_size=1,
+    )
+
+    assert "Line one of the note" in result
+    assert "Line three of the note" in result
+
+
+@pytest.mark.asyncio
+async def test_read_note_rejects_non_positive_pagination(app, test_project):
+    """Fail fast on invalid pagination, matching search_notes/build_context."""
+    with pytest.raises(ValueError, match="page must be >= 1"):
+        await read_note("any-note", project=test_project.name, page=0)
+
+    with pytest.raises(ValueError, match="page_size must be >= 1"):
+        await read_note("any-note", project=test_project.name, page_size=0)
+
+
+@pytest.mark.asyncio
+async def test_read_note_forwards_pagination_to_fallback_search(monkeypatch, app, test_project):
+    """page/page_size must reach the server-side fallback search, not be swallowed."""
+    import importlib
+
+    read_note_module = importlib.import_module("basic_memory.mcp.tools.read_note")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+
+    captured_pages: list[tuple[str, int, int]] = []
+
+    async def fake_search_notes_fn(*, query, search_type, page, page_size, **kwargs):
+        captured_pages.append((search_type, page, page_size))
+        return {"results": [], "current_page": page, "page_size": page_size}
+
+    class FailingKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            raise RuntimeError("force fallback")
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", FailingKnowledgeClient)
+    monkeypatch.setattr(read_note_module, "search_notes", fake_search_notes_fn)
+
+    result = await read_note("missing-note", project=test_project.name, page=2, page_size=3)
+
+    # Title lookup is pinned to page 1 with a fixed lookup size (it exists to
+    # find THE note by exact title); caller page/page_size apply only to the
+    # text-search suggestions.
+    assert captured_pages == [("title", 1, 10), ("text", 2, 3)]
+    assert "Note Not Found" in result
+
+
+@pytest.mark.asyncio
+async def test_read_note_title_fallback_finds_exact_match_on_later_page(
+    monkeypatch, app, test_project
+):
+    """An exact title match is returned even when the caller asks for page > 1.
+
+    The title-match lookup is pinned to page 1 of title results; without the pin,
+    read_note("Exact Title", page=2) would page past the match and return
+    unrelated suggestions instead of the note.
+    """
+    await write_note(
+        project=test_project.name,
+        title="Paged Title Note",
+        directory="test",
+        content="paged title content",
+    )
+
+    import importlib
+    from basic_memory.schemas.memory import memory_url_path
+
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+    direct_identifier = memory_url_path("Paged Title Note")
+
+    class SelectiveKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            # Fail on the direct identifier to force fallback to title search
+            if identifier == direct_identifier:
+                raise RuntimeError("force direct lookup failure")
+            return await super().resolve_entity(identifier, strict=strict)
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", SelectiveKnowledgeClient)
+
+    content = await read_note("Paged Title Note", project=test_project.name, page=2)
+    assert "paged title content" in content
+
+
+@pytest.mark.asyncio
+async def test_read_note_title_fallback_finds_exact_match_with_small_page_size(
+    monkeypatch, app, test_project
+):
+    """An exact title match is returned even when the caller asks for a tiny page_size.
+
+    The title-match lookup uses a fixed lookup size; without it, a higher-ranked
+    fuzzy title ("Foo Bar Foo Bar") would displace the exact title ("Foo Bar")
+    out of a page_size=1 window and read_note("Foo Bar", page_size=1) would
+    return suggestions instead of the note.
+    """
+    await write_note(
+        project=test_project.name,
+        title="Foo Bar Foo Bar",
+        directory="test",
+        content="fuzzy decoy content",
+    )
+    await write_note(
+        project=test_project.name,
+        title="Foo Bar",
+        directory="test",
+        content="exact title content",
+    )
+
+    import importlib
+    from basic_memory.schemas.memory import memory_url_path
+
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+    direct_identifier = memory_url_path("Foo Bar")
+
+    class SelectiveKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            # Fail on the direct identifier to force fallback to title search
+            if identifier == direct_identifier:
+                raise RuntimeError("force direct lookup failure")
+            return await super().resolve_entity(identifier, strict=strict)
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", SelectiveKnowledgeClient)
+
+    content = await read_note("Foo Bar", project=test_project.name, page_size=1)
+    assert "exact title content" in content
+
+
+@pytest.mark.asyncio
+async def test_read_note_title_fallback_pages_past_higher_ranked_fuzzy_titles(
+    monkeypatch, app, test_project
+):
+    """An exact title match is found even when it ranks beyond the first lookup page.
+
+    bm25 ranks titles that repeat the queried phrase above the exact title, so with
+    more than _TITLE_LOOKUP_PAGE_SIZE such decoys the exact match lands on page 2
+    of title results. A single-page lookup would fall through to suggestions even
+    though the note exists; the lookup must page until the exact title is found.
+    """
+    from basic_memory.mcp.tools.read_note import _TITLE_LOOKUP_PAGE_SIZE
+    from basic_memory.mcp.tools.search import search_notes
+
+    for index in range(1, _TITLE_LOOKUP_PAGE_SIZE + 2):
+        await write_note(
+            project=test_project.name,
+            title=f"Deep Page Note Deep Page Note Deep Page Note {index:02d}",
+            directory="test",
+            content=f"fuzzy decoy content {index}",
+        )
+    await write_note(
+        project=test_project.name,
+        title="Deep Page Note",
+        directory="test",
+        content="deep page exact content",
+    )
+
+    # Precondition: the exact title must rank beyond the first lookup page,
+    # otherwise this test would pass even with a single-page lookup.
+    first_page = await search_notes(
+        project=test_project.name,
+        query="Deep Page Note",
+        search_type="title",
+        page=1,
+        page_size=_TITLE_LOOKUP_PAGE_SIZE,
+        output_format="json",
+    )
+    assert isinstance(first_page, dict)
+    first_page_titles = [result["title"] for result in first_page["results"]]
+    assert "Deep Page Note" not in first_page_titles
+    assert first_page["has_more"] is True
+
+    import importlib
+    from basic_memory.schemas.memory import memory_url_path
+
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+    direct_identifier = memory_url_path("Deep Page Note")
+
+    class SelectiveKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            # Fail on the direct identifier to force fallback to title search
+            if identifier == direct_identifier:
+                raise RuntimeError("force direct lookup failure")
+            return await super().resolve_entity(identifier, strict=strict)
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", SelectiveKnowledgeClient)
+
+    content = await read_note("Deep Page Note", project=test_project.name)
+    assert "deep page exact content" in content
+
+
+@pytest.mark.asyncio
+async def test_read_note_title_lookup_stops_at_page_cap(monkeypatch, app, test_project):
+    """The title lookup is bounded: after the page cap it falls through to suggestions."""
+    import importlib
+
+    read_note_module = importlib.import_module("basic_memory.mcp.tools.read_note")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+
+    captured_pages: list[tuple[str, int]] = []
+
+    async def fake_search_notes_fn(*, query, search_type, page, page_size, **kwargs):
+        captured_pages.append((search_type, page))
+        if search_type == "title":
+            # Endless fuzzy titles: every page is full and reports more available,
+            # simulating a pathological knowledge base that never yields the note.
+            return {
+                "results": [
+                    {
+                        "title": f"Fuzzy {page}-{index}",
+                        "permalink": f"docs/fuzzy-{page}-{index}",
+                        "content": "",
+                        "type": "entity",
+                        "score": 1.0,
+                        "file_path": f"docs/fuzzy-{page}-{index}.md",
+                    }
+                    for index in range(page_size)
+                ],
+                "current_page": page,
+                "page_size": page_size,
+                "has_more": True,
+            }
+        return {"results": [], "current_page": page, "page_size": page_size}
+
+    class FailingKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            raise RuntimeError("force fallback")
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", FailingKnowledgeClient)
+    monkeypatch.setattr(read_note_module, "search_notes", fake_search_notes_fn)
+
+    result = await read_note("Pathological Note", project=test_project.name)
+
+    title_pages = [page for search_type, page in captured_pages if search_type == "title"]
+    assert title_pages == list(range(1, read_note_module._TITLE_LOOKUP_MAX_PAGES + 1))
+    assert "Note Not Found" in result
+
+
+@pytest.mark.asyncio
+async def test_read_note_related_results_list_full_search_page(monkeypatch, app, test_project):
+    """Suggestions list the whole returned search page instead of a hardcoded cap of 5."""
+    import importlib
+
+    read_note_module = importlib.import_module("basic_memory.mcp.tools.read_note")
+    clients_mod = importlib.import_module("basic_memory.mcp.clients")
+    OriginalKnowledgeClient = clients_mod.KnowledgeClient
+
+    candidates = [
+        {
+            "title": f"Related {index}",
+            "permalink": f"docs/related-{index}",
+            "content": "",
+            "type": "entity",
+            "score": 1.0,
+            "file_path": f"docs/related-{index}.md",
+        }
+        for index in range(1, 7)
+    ]
+
+    async def fake_search_notes_fn(*, query, search_type, **kwargs):
+        if search_type == "title":
+            return {"results": [], "current_page": 1, "page_size": 10}
+        return {"results": candidates, "current_page": 1, "page_size": 10}
+
+    class FailingKnowledgeClient(OriginalKnowledgeClient):
+        async def resolve_entity(self, identifier: str, *, strict: bool = False) -> str:
+            raise RuntimeError("force fallback")
+
+    monkeypatch.setattr(clients_mod, "KnowledgeClient", FailingKnowledgeClient)
+    monkeypatch.setattr(read_note_module, "search_notes", fake_search_notes_fn)
+
+    text_result = await read_note("missing-note", project=test_project.name)
+    assert "## 6. Related 6" in text_result
+
+    json_result = await read_note(
+        "missing-note",
+        project=test_project.name,
+        output_format="json",
+    )
+    assert isinstance(json_result, dict)
+    assert len(json_result["related_results"]) == 6
+
+
@pytest.mark.asyncio
 async def test_read_note_title_fallback_requires_exact_title_match(monkeypatch, app, test_project):
    """Do not fetch note content when title-search returns only fuzzy matches."""
@@ -1,11 +1,15 @@
 """Tests for search MCP tools."""

+import inspect
+
 import pytest
 from contextlib import asynccontextmanager
 from datetime import datetime, timedelta
 from types import SimpleNamespace
 from typing import cast

+from pydantic import TypeAdapter
+
 from basic_memory.mcp.tools import write_note
 from basic_memory.mcp.tools.search import (
    search_notes,
@@ -1622,6 +1626,74 @@ async def test_search_notes_tag_prefix_with_remaining_text(monkeypatch):
    assert captured_payload["text"] == "authentication"


+# --- Tests for comma-separated tags parameter (#910) ----------------------------
+
+
+def test_search_notes_tags_annotation_splits_comma_strings():
+    """The tags parameter annotation must parse every documented input form (#910).
+
+    Direct function calls bypass the BeforeValidator, so validate through the same
+    Annotated metadata pydantic applies on the MCP path. coerce_list wrapped a bare
+    comma string as the single literal tag ["a,b"]; parse_tags splits it like the
+    tag: query shorthand and write_note's tags convention.
+    """
+    annotation = inspect.signature(search_notes).parameters["tags"].annotation
+    adapter = TypeAdapter(annotation)
+
+    real_list = adapter.validate_python(["a", "b"])
+    comma_string = adapter.validate_python("a,b")
+    json_string = adapter.validate_python('["a", "b"]')
+    single_string = adapter.validate_python("a")
+
+    assert real_list == ["a", "b"]
+    # The comma string and the real list must behave identically (the #910 bug).
+    assert comma_string == real_list
+    assert json_string == real_list
+    assert single_string == ["a"]
+
+
+@pytest.mark.asyncio
+async def test_search_notes_tags_comma_string_filters_via_mcp(mcp, client, test_project):
+    """tags="alpha,beta" through the real MCP layer must match like a real list (#910)."""
+    from fastmcp import Client
+
+    async with Client(mcp) as mcp_client:
+        await mcp_client.call_tool(
+            "write_note",
+            {
+                "project": test_project.name,
+                "title": "Tag Split Note",
+                "directory": "test",
+                "content": "# Tag Split Note\nTagSplitToken body",
+                "tags": ["alpha", "beta"],
+            },
+        )
+
+        async def found(tags_value: object) -> bool:
+            result = await mcp_client.call_tool(
+                "search_notes",
+                {
+                    "project": test_project.name,
+                    "query": "TagSplitToken",
+                    "search_type": "text",
+                    "tags": tags_value,
+                },
+            )
+            return "Tag Split Note" in result.content[0].text
+
+        as_list = await found(["alpha", "beta"])
+        as_comma_string = await found("alpha,beta")
+        as_json_string = await found('["alpha", "beta"]')
+        as_single_string = await found("alpha")
+
+        assert as_list, "real-list tags must match (sanity)"
+        assert as_comma_string == as_list, "comma string must behave like the real list"
+        assert as_json_string == as_list
+        assert as_single_string == as_list
+        # Negative control: the filter is actually applied, not silently dropped.
+        assert not await found("gamma")
+
+
 # --- Tests for text output format (#641) -----------------------------------


@@ -109,6 +109,8 @@ async def test_read_note_emits_root_operation_and_project_context(
            "tool_name": "read_note",
            "requested_project": test_project.name,
            "requested_project_id": None,
+            "page": 1,
+            "page_size": 10,
            "output_format": "json",
            "include_frontmatter": True,
        },
@@ -466,3 +466,64 @@ async def test_observation_permalink_short_content_unchanged(
        # Short content should be fully included (after permalink normalization)
        # The generate_permalink function normalizes the content
        assert "short-observation-content" in permalink.lower()
+
+
+@pytest.mark.asyncio
+async def test_observation_permalink_disambiguates_truncated_content(
+    session_maker: async_sessionmaker, repo, test_project: Project
+):
+    """Regression test for issue #909: shared 200-char prefixes must not collide.
+
+    Truncating content to 200 chars (PostgreSQL btree limit) made two distinct
+    observations with the same category and an identical 200-char prefix produce
+    the same synthetic permalink, silently dropping the second from the search
+    index. A digest of the full content now disambiguates them.
+    """
+    async with db.scoped_session(session_maker) as session:
+        entity = Entity(
+            project_id=test_project.id,
+            title="test_entity",
+            note_type="test",
+            permalink="test/test-entity",
+            file_path="test/test_entity.md",
+            content_type="text/markdown",
+            created_at=datetime.now(timezone.utc),
+            updated_at=datetime.now(timezone.utc),
+        )
+        session.add(entity)
+        await session.flush()
+
+        shared_prefix = "x" * 210  # identical beyond the 200-char truncation point
+        obs_alpha = Observation(
+            project_id=test_project.id,
+            entity_id=entity.id,
+            content=f"{shared_prefix} ALPHA_UNIQUE_MARKER",
+            category="note",
+        )
+        obs_beta = Observation(
+            project_id=test_project.id,
+            entity_id=entity.id,
+            content=f"{shared_prefix} BETA_UNIQUE_MARKER",
+            category="note",
+        )
+        session.add_all([obs_alpha, obs_beta])
+        await session.flush()
+
+        # Distinct content must yield distinct permalinks despite the shared prefix
+        assert obs_alpha.permalink != obs_beta.permalink
+
+        # The digest suffix must keep permalinks under the PostgreSQL btree budget
+        assert len(obs_alpha.permalink) < 300
+        assert len(obs_beta.permalink) < 300
+
+        # Truly identical long content must still produce the same permalink so
+        # exact duplicates continue to dedupe in the search index
+        obs_beta_dup = Observation(
+            project_id=test_project.id,
+            entity_id=entity.id,
+            content=f"{shared_prefix} BETA_UNIQUE_MARKER",
+            category="note",
+        )
+        session.add(obs_beta_dup)
+        await session.flush()
+        assert obs_beta_dup.permalink == obs_beta.permalink
@@ -0,0 +1,434 @@
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+import pytest
+from typer.testing import CliRunner
+
+from scripts import bm_bossbot_status
+
+
+def _event_payload(body: str = "Event snapshot body") -> dict[str, object]:
+    return {
+        "repository": {"full_name": "basicmachines-co/basic-memory"},
+        "pull_request": {
+            "number": 925,
+            "body": body,
+            "head": {"sha": "abc123"},
+        },
+    }
+
+
+def test_status_script_is_uv_typer_entrypoint() -> None:
+    source = bm_bossbot_status.__file__
+    assert source is not None
+    text = open(source, encoding="utf-8").read()
+
+    assert text.startswith("#!/usr/bin/env -S uv run --script\n")
+    assert "# /// script" in text
+    assert "typer" in text
+    assert hasattr(bm_bossbot_status, "app")
+
+
+def test_status_payload_uses_required_context() -> None:
+    payload = bm_bossbot_status.build_status_payload(
+        state="pending",
+        description="BM Bossbot is reviewing this head SHA",
+        target_url="https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+    )
+
+    assert payload == {
+        "state": "pending",
+        "context": "BM Bossbot Approval",
+        "description": "BM Bossbot is reviewing this head SHA",
+        "target_url": "https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+    }
+
+
+def test_upsert_summary_block_replaces_existing_block() -> None:
+    body = "\n".join(
+        [
+            "Intro",
+            "<!-- BM_BOSSBOT_SUMMARY:start -->",
+            "Old summary",
+            "<!-- BM_BOSSBOT_SUMMARY:end -->",
+            "Footer",
+        ]
+    )
+
+    updated = bm_bossbot_status.upsert_summary_block(body, "New summary")
+
+    assert "Old summary" not in updated
+    assert "New summary" in updated
+    assert updated.startswith("Intro")
+    assert updated.endswith("Footer")
+
+
+def test_finalize_review_fetches_current_pr_body_before_upserting(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    event_path = tmp_path / "event.json"
+    event_path.write_text(json.dumps(_event_payload()), encoding="utf-8")
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+
+    updated_bodies: list[str] = []
+    statuses: list[Mapping[str, str]] = []
+
+    def fake_get_pull_request_body(*, token: str, repo: str, number: int) -> str:
+        assert token == "token"
+        assert repo == "basicmachines-co/basic-memory"
+        assert number == 925
+        return "Current body edited while the workflow was running"
+
+    def fake_update_pull_request_body(*, token: str, repo: str, number: int, body: str) -> None:
+        updated_bodies.append(body)
+
+    def fake_set_commit_status(
+        *,
+        token: str,
+        repo: str,
+        sha: str,
+        payload: Mapping[str, str],
+    ) -> None:
+        statuses.append(payload)
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_body", fake_get_pull_request_body)
+    monkeypatch.setattr(
+        bm_bossbot_status, "update_pull_request_body", fake_update_pull_request_body
+    )
+    monkeypatch.setattr(bm_bossbot_status, "set_commit_status", fake_set_commit_status)
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", lambda **_: 0)
+
+    result = bm_bossbot_status.finalize_review(
+        event_path=event_path,
+        trusted=True,
+        repo=None,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+        token_env="GITHUB_TOKEN",
+    )
+
+    assert result.approved is True
+    assert "Current body edited while the workflow was running" in updated_bodies[0]
+    assert "Event snapshot body" not in updated_bodies[0]
+    assert "Gate: deterministic" in updated_bodies[0]
+    assert statuses[0]["state"] == "success"
+
+
+def test_finalize_review_blocks_approval_on_unresolved_review_threads(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    event_path = tmp_path / "event.json"
+    event_path.write_text(json.dumps(_event_payload()), encoding="utf-8")
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+
+    statuses: list[Mapping[str, str]] = []
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_body", lambda **_: "Body")
+    monkeypatch.setattr(bm_bossbot_status, "update_pull_request_body", lambda **_: None)
+    monkeypatch.setattr(
+        bm_bossbot_status,
+        "set_commit_status",
+        lambda *, token, repo, sha, payload: statuses.append(payload),
+    )
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", lambda **_: 2)
+
+    result = bm_bossbot_status.finalize_review(
+        event_path=event_path,
+        trusted=True,
+        repo=None,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+        token_env="GITHUB_TOKEN",
+    )
+
+    assert result.approved is False
+    assert result.state == "failure"
+    assert result.description == "BM Bossbot found 2 unresolved review thread(s)"
+    assert statuses[0]["state"] == "failure"
+
+
+def test_finalize_review_fails_untrusted_author_without_counting_threads(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    event_path = tmp_path / "event.json"
+    event_path.write_text(json.dumps(_event_payload()), encoding="utf-8")
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_body", lambda **_: "Body")
+    monkeypatch.setattr(bm_bossbot_status, "update_pull_request_body", lambda **_: None)
+    monkeypatch.setattr(bm_bossbot_status, "set_commit_status", lambda **_: None)
+
+    def fail_count(**_: object) -> int:
+        raise AssertionError("thread count must not run for untrusted authors")
+
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", fail_count)
+
+    result = bm_bossbot_status.finalize_review(
+        event_path=event_path,
+        trusted=False,
+        repo=None,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+        token_env="GITHUB_TOKEN",
+    )
+
+    assert result.approved is False
+    assert result.description == "BM Bossbot only gates owner/member/collaborator PRs"
+
+
+def test_count_unresolved_review_threads_pages_through_graphql_results(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    pages = [
+        {
+            "data": {
+                "repository": {
+                    "pullRequest": {
+                        "reviewThreads": {
+                            "pageInfo": {"hasNextPage": True, "endCursor": "CUR"},
+                            "nodes": [{"isResolved": False}, {"isResolved": True}],
+                        }
+                    }
+                }
+            }
+        },
+        {
+            "data": {
+                "repository": {
+                    "pullRequest": {
+                        "reviewThreads": {
+                            "pageInfo": {"hasNextPage": False, "endCursor": None},
+                            "nodes": [{"isResolved": False}],
+                        }
+                    }
+                }
+            }
+        },
+    ]
+    cursors: list[object] = []
+
+    # Signature mirrors bm_bossbot_status._github_request (payload: Mapping[str, Any] | None).
+    def fake_github_request(
+        *, method: str, path: str, token: str, payload: Mapping[str, Any] | None = None
+    ) -> object:
+        assert method == "POST"
+        assert path == "/graphql"
+        assert payload is not None
+        cursors.append(payload["variables"]["cursor"])
+        return pages.pop(0)
+
+    monkeypatch.setattr(bm_bossbot_status, "_github_request", fake_github_request)
+
+    count = bm_bossbot_status.count_unresolved_review_threads(
+        token="token", repo="basicmachines-co/basic-memory", number=925
+    )
+
+    assert count == 2
+    assert cursors == [None, "CUR"]
+
+
+def test_recheck_marks_failure_when_threads_are_unresolved(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+    statuses: list[Mapping[str, str]] = []
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_head_sha", lambda **_: "abc123")
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", lambda **_: 3)
+    monkeypatch.setattr(
+        bm_bossbot_status,
+        "set_commit_status",
+        lambda *, token, repo, sha, payload: statuses.append({"sha": sha, **payload}),
+    )
+
+    bm_bossbot_status.recheck_threads(
+        repo="basicmachines-co/basic-memory",
+        number=925,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/2",
+        token_env="GITHUB_TOKEN",
+    )
+
+    assert statuses[0]["sha"] == "abc123"
+    assert statuses[0]["state"] == "failure"
+    assert "3 unresolved review thread(s)" in statuses[0]["description"]
+
+
+def test_recheck_restores_prior_approval_when_threads_resolve(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+    statuses: list[Mapping[str, str]] = []
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_head_sha", lambda **_: "abc123")
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", lambda **_: 0)
+    monkeypatch.setattr(bm_bossbot_status, "head_sha_was_approved", lambda **_: True)
+    monkeypatch.setattr(
+        bm_bossbot_status,
+        "set_commit_status",
+        lambda *, token, repo, sha, payload: statuses.append(payload),
+    )
+
+    bm_bossbot_status.recheck_threads(
+        repo="basicmachines-co/basic-memory",
+        number=925,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/2",
+        token_env="GITHUB_TOKEN",
+    )
+
+    assert statuses[0]["state"] == "success"
+    assert statuses[0]["description"] == "BM Bossbot approved this head SHA"
+
+
+def test_recheck_leaves_status_alone_without_prior_approval(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_head_sha", lambda **_: "abc123")
+    monkeypatch.setattr(bm_bossbot_status, "count_unresolved_review_threads", lambda **_: 0)
+    monkeypatch.setattr(bm_bossbot_status, "head_sha_was_approved", lambda **_: False)
+
+    def fail_set_status(**_: object) -> None:
+        raise AssertionError("status must not change without a prior approval")
+
+    monkeypatch.setattr(bm_bossbot_status, "set_commit_status", fail_set_status)
+
+    bm_bossbot_status.recheck_threads(
+        repo="basicmachines-co/basic-memory",
+        number=925,
+        run_url="https://github.com/basicmachines-co/basic-memory/actions/runs/2",
+        token_env="GITHUB_TOKEN",
+    )
+
+
+def test_head_sha_was_approved_matches_only_the_approval_record(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    history = [
+        {
+            "context": "BM Bossbot Approval",
+            "state": "failure",
+            "description": "BM Bossbot found 2 unresolved review thread(s)",
+        },
+        {
+            "context": "BM Bossbot Approval",
+            "state": "success",
+            "description": "BM Bossbot approved this head SHA",
+        },
+        {"context": "license/cla", "state": "success", "description": "ok"},
+    ]
+
+    def _paged(pages: list[list[dict]]):
+        def fake(*, method: str, path: str, token: str, payload=None):
+            # Anchor on "&page=N" — a bare "page=N" substring also matches
+            # "per_page=100", which served page 1 forever and hung the loop.
+            for number, page in enumerate(pages, start=1):
+                if f"&page={number}" in path:
+                    return page
+            return []
+
+        return fake
+
+    monkeypatch.setattr(bm_bossbot_status, "_github_request", _paged([history]))
+    assert (
+        bm_bossbot_status.head_sha_was_approved(
+            token="token", repo="basicmachines-co/basic-memory", sha="abc123"
+        )
+        is True
+    )
+
+    monkeypatch.setattr(bm_bossbot_status, "_github_request", _paged([history[:1]]))
+    assert (
+        bm_bossbot_status.head_sha_was_approved(
+            token="token", repo="basicmachines-co/basic-memory", sha="abc123"
+        )
+        is False
+    )
+
+
+def test_head_sha_was_approved_pages_past_first_page_of_statuses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The recheck path can post >100 statuses; the approval may sit on page 2+."""
+    failure = {
+        "context": "BM Bossbot Approval",
+        "state": "failure",
+        "description": "BM Bossbot found 1 unresolved review thread(s)",
+    }
+    approval = {
+        "context": "BM Bossbot Approval",
+        "state": "success",
+        "description": "BM Bossbot approved this head SHA",
+    }
+    pages_served: list[str] = []
+
+    def fake(*, method: str, path: str, token: str, payload=None):
+        pages_served.append(path)
+        if "&page=1" in path:
+            return [failure] * 100
+        if "&page=2" in path:
+            return [approval]
+        return []
+
+    monkeypatch.setattr(bm_bossbot_status, "_github_request", fake)
+
+    assert (
+        bm_bossbot_status.head_sha_was_approved(
+            token="token", repo="basicmachines-co/basic-memory", sha="abc123"
+        )
+        is True
+    )
+    assert len(pages_served) == 2
+
+
+def test_finalize_cli_exits_nonzero_for_untrusted_author(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    event_path = tmp_path / "event.json"
+    event_path.write_text(json.dumps(_event_payload(body="Current body")), encoding="utf-8")
+    monkeypatch.setenv("GITHUB_TOKEN", "token")
+
+    updated_bodies: list[str] = []
+    statuses: list[Mapping[str, str]] = []
+
+    def fake_get_pull_request_body(*, token: str, repo: str, number: int) -> str:
+        return "Current body"
+
+    def fake_update_pull_request_body(*, token: str, repo: str, number: int, body: str) -> None:
+        updated_bodies.append(body)
+
+    def fake_set_commit_status(
+        *,
+        token: str,
+        repo: str,
+        sha: str,
+        payload: Mapping[str, str],
+    ) -> None:
+        statuses.append(payload)
+
+    monkeypatch.setattr(bm_bossbot_status, "get_pull_request_body", fake_get_pull_request_body)
+    monkeypatch.setattr(
+        bm_bossbot_status, "update_pull_request_body", fake_update_pull_request_body
+    )
+    monkeypatch.setattr(bm_bossbot_status, "set_commit_status", fake_set_commit_status)
+
+    result = CliRunner().invoke(
+        bm_bossbot_status.app,
+        [
+            "finalize",
+            "--event",
+            str(event_path),
+            "--trusted",
+            "false",
+            "--repo",
+            "basicmachines-co/basic-memory",
+            "--run-url",
+            "https://github.com/basicmachines-co/basic-memory/actions/runs/1",
+        ],
+    )
+
+    assert result.exit_code == 1
+    assert "BM Bossbot only gates owner/member/collaborator PRs" in updated_bodies[0]
+    assert statuses[0]["state"] == "failure"
@@ -0,0 +1,445 @@
+import json
+from pathlib import Path
+
+import pytest
+from click import unstyle
+from typer.testing import CliRunner
+
+from scripts import generate_infographic, generate_pr_infographic
+
+
+def test_infographic_scripts_are_uv_typer_entrypoints() -> None:
+    for module in (generate_infographic, generate_pr_infographic):
+        source = module.__file__
+        assert source is not None
+        text = Path(source).read_text(encoding="utf-8")
+
+        assert text.startswith("#!/usr/bin/env -S uv run --script\n")
+        assert "# /// script" in text
+        assert "typer" in text
+        assert hasattr(module, "app")
+
+
+def test_generate_pr_infographic_cli_help_exposes_useful_options() -> None:
+    result = CliRunner().invoke(generate_pr_infographic.app, ["--help"])
+    help_text = unstyle(result.output)
+
+    assert result.exit_code == 0
+    assert "--pr-number" in help_text
+    assert "--pr-context-file" in help_text
+    assert "--output" in help_text
+    assert "--theme" in help_text
+    assert "--provenance-output" in help_text
+    assert "--print-prompt" in help_text
+    assert "--dry-run" in help_text
+
+
+def test_extract_pr_content_strips_managed_bot_blocks() -> None:
+    body = "\n".join(
+        [
+            "## Summary",
+            "Adds per-workspace rclone remotes for Team push/pull.",
+            "<!-- BM_BOSSBOT_SUMMARY:start -->",
+            "Reviewed SHA: abc123",
+            "Verdict: approve",
+            "<!-- BM_BOSSBOT_SUMMARY:end -->",
+            "<!-- pr-infographic:start -->",
+            "![BM Bossbot image for PR #42](https://example.test/img.webp)",
+            "<!-- pr-infographic:end -->",
+            "<!-- BM_INFOGRAPHIC_PROVENANCE:start -->",
+            "provenance details",
+            "<!-- BM_INFOGRAPHIC_PROVENANCE:end -->",
+            "## Test plan",
+            "pytest passes.",
+        ]
+    )
+
+    content = generate_pr_infographic.extract_pr_content(body)
+
+    assert "Adds per-workspace rclone remotes" in content
+    assert "pytest passes." in content
+    assert "Verdict: approve" not in content
+    assert "Reviewed SHA" not in content
+    assert "provenance details" not in content
+    assert "BM Bossbot image for PR" not in content
+
+
+def test_extract_pr_content_handles_body_without_managed_blocks() -> None:
+    assert generate_pr_infographic.extract_pr_content("Plain description") == "Plain description"
+
+
+def test_build_change_shape_digests_delivery_context() -> None:
+    context = {
+        "labels": [{"name": "enhancement"}, {"name": "cloud"}],
+        "closingIssuesReferences": [{"number": 581, "title": "edit_note recovery"}],
+        "commits": [
+            {"messageHeadline": "fix(mcp): recover edit_note"},
+            {"messageHeadline": "fix(api): canonicalize sync-file paths"},
+        ],
+        "files": [
+            {"path": "src/basic_memory/mcp/tools/edit_note.py", "additions": 120, "deletions": 30},
+            {"path": "tests/mcp/test_tool_edit_note.py", "additions": 80, "deletions": 5},
+        ],
+    }
+
+    context["commits"].append({"messageHeadline": "Merge branch 'main' into fix/581"})
+    shape = generate_pr_infographic.build_change_shape(context)
+
+    assert "Labels: enhancement, cloud" in shape
+    assert "#581: edit_note recovery" in shape
+    assert "Commit subjects (2 total):" in shape
+    assert "Merge branch" not in shape
+    assert "fix(mcp): recover edit_note" in shape
+    assert "Files changed (2 total, +200/-35):" in shape
+    assert "src/basic_memory/mcp/tools/edit_note.py (+120/-30)" in shape
+
+
+def test_build_change_shape_caps_long_lists_and_handles_empty_context() -> None:
+    context = {
+        "commits": [{"messageHeadline": f"commit {i}"} for i in range(15)],
+        "files": [{"path": f"file-{i}.py", "additions": i, "deletions": 0} for i in range(15)],
+    }
+
+    shape = generate_pr_infographic.build_change_shape(context)
+
+    assert "Commit subjects (15 total):" in shape
+    assert "- ... and 5 more" in shape
+    assert "- ... and 5 more files" in shape
+    # Files are ranked by churn, so the biggest file leads the list.
+    assert shape.index("file-14.py") < shape.index("file-5.py")
+
+    assert (
+        generate_pr_infographic.build_change_shape({}) == "(no additional change context available)"
+    )
+
+
+def test_extract_infographic_theme_from_pr_body() -> None:
+    body = "\n".join(
+        [
+            "Before",
+            "<!-- BM_INFOGRAPHIC_THEME:start -->",
+            "Italian movie poster with a release-route map",
+            "<!-- BM_INFOGRAPHIC_THEME:end -->",
+            "After",
+        ]
+    )
+
+    theme = generate_pr_infographic.extract_infographic_theme(body)
+
+    assert theme == "Italian movie poster with a release-route map"
+
+
+def test_extract_infographic_theme_is_optional() -> None:
+    assert generate_pr_infographic.extract_infographic_theme("No theme") is None
+
+
+def test_select_image_theme_reports_source() -> None:
+    body = "\n".join(
+        [
+            "<!-- BM_INFOGRAPHIC_THEME:start -->",
+            "paintings: Rembrandt-inspired merge gate",
+            "<!-- BM_INFOGRAPHIC_THEME:end -->",
+        ]
+    )
+
+    from_body = generate_pr_infographic.select_image_theme(
+        pr_number=42,
+        pr_title="feat(ci): add a merge gate",
+        pr_body=body,
+        theme_override=None,
+    )
+    from_cli = generate_pr_infographic.select_image_theme(
+        pr_number=42,
+        pr_title="feat(ci): add a merge gate",
+        pr_body=body,
+        theme_override="80's action movies",
+    )
+    from_auto = generate_pr_infographic.select_image_theme(
+        pr_number=42,
+        pr_title="feat(ci): add a merge gate",
+        pr_body="No theme",
+        theme_override=None,
+    )
+
+    assert from_body.theme == "paintings: Rembrandt-inspired merge gate"
+    assert from_body.source == generate_pr_infographic.ThemeSource.PR_BODY
+    assert from_cli.theme == "80's action movies"
+    assert from_cli.source == generate_pr_infographic.ThemeSource.CLI
+    assert from_auto.theme in generate_pr_infographic.BM_IMAGE_THEME_POOL
+    assert from_auto.source == generate_pr_infographic.ThemeSource.AUTO
+
+
+def test_build_infographic_prompt_depicts_pr_content_not_review_outcome() -> None:
+    prompt = generate_pr_infographic.build_infographic_prompt(
+        pr_number=42,
+        pr_title="feat(sync): stream large files during cloud sync",
+        pr_content="Streams PDFs in chunks instead of loading them fully into memory.",
+        change_shape="Labels: sync\nFiles changed (3 total, +90/-20):\n- src/basic_memory/sync/x.py (+80/-15)",
+        theme="WWII propaganda posters with home-front logistics routes",
+        theme_source=generate_pr_infographic.ThemeSource.CLI,
+    )
+
+    assert "PR #42" in prompt
+    assert "stream large files during cloud sync" in prompt
+    assert "Streams PDFs in chunks" in prompt
+    assert "WWII propaganda posters" in prompt
+    assert "User-supplied visual direction" in prompt
+    assert "style inspiration only" in prompt
+    assert "polished landscape WebP editorial image" in prompt
+    assert "image-first composition" in prompt
+    assert "symbolic tableau" in prompt
+    assert "Do not render an infographic" in prompt
+    assert "dashboard" in prompt
+    assert "flowchart" in prompt
+    assert "copyrighted characters" in prompt
+    # The subject is the change itself; review-process imagery is banned.
+    assert "CONTENT of the pull request" in prompt
+    assert "do not depict review verdicts" in prompt
+    assert "approval" in prompt.lower()
+    assert "stamps" in prompt
+    assert "checkmarks" in prompt
+    # Change shape grounds the imagery but must not become captions.
+    assert "Change shape" in prompt
+    assert "src/basic_memory/sync/x.py" in prompt
+    assert "never render file" in prompt
+    # The old prompt fed the review summary and named the approval status,
+    # which produced literal "BOSSBOT APPROVED" stamp images.
+    assert "BM Bossbot summary:" not in prompt
+    assert "BM Bossbot Approval" not in prompt
+
+
+def test_build_infographic_provenance_block_includes_image_choices_without_prompt() -> None:
+    block = generate_pr_infographic.build_infographic_provenance_block(
+        pr_number=42,
+        output_path=Path("docs/assets/infographics/pr-42.webp"),
+        model="gpt-image-2",
+        size="1536x1024",
+        quality="high",
+        theme="classic black-and-white photography",
+        theme_source=generate_pr_infographic.ThemeSource.CLI,
+    )
+
+    assert generate_pr_infographic.PROVENANCE_START in block
+    assert generate_pr_infographic.PROVENANCE_END in block
+    assert "BM Bossbot image choices" in block
+    assert "Generated asset: `docs/assets/infographics/pr-42.webp`" in block
+    assert "Image model: `gpt-image-2`" in block
+    assert "Size: `1536x1024`" in block
+    assert "Quality: `high`" in block
+    assert "Image mode: `editorial-image`" in block
+    assert "Theme source: `cli`" in block
+    assert "classic black-and-white photography" in block
+    assert "Image prompt sent to" not in block
+    assert "Images API revised prompt" not in block
+
+
+def test_upsert_managed_block_appends_and_replaces() -> None:
+    first = "\n".join(
+        [
+            generate_pr_infographic.PROVENANCE_START,
+            "first",
+            generate_pr_infographic.PROVENANCE_END,
+        ]
+    )
+    second = "\n".join(
+        [
+            generate_pr_infographic.PROVENANCE_START,
+            "second",
+            generate_pr_infographic.PROVENANCE_END,
+        ]
+    )
+
+    appended = generate_pr_infographic.upsert_managed_block(
+        "Existing body",
+        block=first,
+        start=generate_pr_infographic.PROVENANCE_START,
+        end=generate_pr_infographic.PROVENANCE_END,
+    )
+    replaced = generate_pr_infographic.upsert_managed_block(
+        appended,
+        block=second,
+        start=generate_pr_infographic.PROVENANCE_START,
+        end=generate_pr_infographic.PROVENANCE_END,
+    )
+
+    assert appended == f"Existing body\n\n{first}\n"
+    assert "first" not in replaced
+    assert "second" in replaced
+    assert replaced.count(generate_pr_infographic.PROVENANCE_START) == 1
+
+
+def test_build_infographic_prompt_uses_auto_theme_as_visual_direction() -> None:
+    theme = generate_pr_infographic.select_image_theme(
+        pr_number=42,
+        pr_title="feat(ci): add a merge gate",
+        pr_body="No theme",
+        theme_override=None,
+    )
+    prompt = generate_pr_infographic.build_infographic_prompt(
+        pr_number=42,
+        pr_title="feat(ci): add a merge gate",
+        pr_content="Adds a deterministic merge gate for pull requests.",
+        change_shape="(no additional change context available)",
+        theme=theme.theme,
+        theme_source=theme.source,
+    )
+
+    assert "Selected BM visual direction" in prompt
+    assert theme.theme in prompt
+    assert "Use image-first composition" in prompt
+    assert "movie poster" in prompt
+    assert "painting" in prompt
+    assert "classic photograph" in prompt
+    assert "scene" in prompt
+    assert "poster" in prompt
+    assert "cover image" in prompt
+    assert "symbolic tableau" in prompt
+    assert "Use at most a short title" in prompt
+    assert "Do not render an infographic" in prompt
+    assert "dashboard" in prompt
+    assert "flowchart" in prompt
+    assert "bullet-list panel" in prompt
+
+
+@pytest.mark.parametrize("flag", ["--print-prompt", "--dry-run"])
+def test_generate_pr_infographic_can_print_prompt_without_image_call(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    flag: str,
+) -> None:
+    context_file = tmp_path / "pr-context.json"
+    context_file.write_text(
+        json.dumps(
+            {
+                "title": "feat(ci): add a merge gate",
+                "body": "\n".join(
+                    [
+                        "Adds a deterministic merge gate for pull requests.",
+                        "<!-- BM_BOSSBOT_SUMMARY:start -->",
+                        "Verdict: approve",
+                        "Summary: review artifact that must not reach the image.",
+                        "<!-- BM_BOSSBOT_SUMMARY:end -->",
+                        "<!-- BM_INFOGRAPHIC_THEME:start -->",
+                        "space exploration and astronomy",
+                        "<!-- BM_INFOGRAPHIC_THEME:end -->",
+                    ]
+                ),
+                "labels": [{"name": "ci"}],
+                "commits": [{"messageHeadline": "feat(ci): add a merge gate"}],
+                "files": [{"path": ".github/workflows/gate.yml", "additions": 40, "deletions": 2}],
+                "closingIssuesReferences": [{"number": 7, "title": "merge gate"}],
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    def fail_generate_image_result(**_: object) -> generate_infographic.GeneratedImage:
+        raise AssertionError("print-prompt mode must not call image generation")
+
+    monkeypatch.setattr(
+        generate_pr_infographic, "generate_image_result", fail_generate_image_result
+    )
+    output = tmp_path / "docs/assets/infographics/pr-42.webp"
+
+    result = CliRunner().invoke(
+        generate_pr_infographic.app,
+        [
+            "--pr-number",
+            "42",
+            "--pr-context-file",
+            str(context_file),
+            "--output",
+            str(output),
+            flag,
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert (
+        "Create a polished landscape WebP editorial image for Basic Memory PR #42" in result.output
+    )
+    assert "feat(ci): add a merge gate" in result.output
+    assert "Adds a deterministic merge gate" in result.output
+    assert "space exploration and astronomy" in result.output
+    assert "Labels: ci" in result.output
+    assert ".github/workflows/gate.yml" in result.output
+    assert "#7: merge gate" in result.output
+    assert "image-first composition" in result.output
+    assert "Do not render an infographic" in result.output
+    assert "Verdict: approve" not in result.output
+    assert "must not reach the image" not in result.output
+    assert not output.exists()
+
+
+def test_generate_pr_infographic_writes_provenance_after_image_generation(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    context_file = tmp_path / "pr-context.json"
+    context_file.write_text(
+        json.dumps(
+            {
+                "title": "feat(ci): add a merge gate",
+                "body": "\n".join(
+                    [
+                        "Adds a merge gate.",
+                        "<!-- BM_INFOGRAPHIC_THEME:start -->",
+                        "paintings: Rembrandt-inspired merge gate",
+                        "<!-- BM_INFOGRAPHIC_THEME:end -->",
+                    ]
+                ),
+            }
+        ),
+        encoding="utf-8",
+    )
+
+    def fake_generate_image_result(**kwargs: object) -> generate_infographic.GeneratedImage:
+        output_path = kwargs["output_path"]
+        assert isinstance(output_path, Path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(b"fake-webp")
+        return generate_infographic.GeneratedImage(
+            path=output_path,
+            revised_prompt="A Rembrandt-inspired painting of a robot guarding a merge gate.",
+        )
+
+    monkeypatch.setattr(
+        generate_pr_infographic, "generate_image_result", fake_generate_image_result
+    )
+    output = tmp_path / "docs/assets/infographics/pr-42.webp"
+    provenance = tmp_path / "provenance.md"
+
+    result = CliRunner().invoke(
+        generate_pr_infographic.app,
+        [
+            "--pr-number",
+            "42",
+            "--pr-context-file",
+            str(context_file),
+            "--output",
+            str(output),
+            "--provenance-output",
+            str(provenance),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert output.exists()
+    text = provenance.read_text(encoding="utf-8")
+    assert "Generated asset:" in text
+    assert "Image mode: `editorial-image`" in text
+    assert "Theme source: `pr-body`" in text
+    assert "paintings: Rembrandt-inspired merge gate" in text
+    assert "Image prompt sent to" not in text
+    assert "Images API revised prompt" not in text
+    assert "robot guarding a merge gate" not in text
+    assert "Adds a merge gate" not in text
+
+
+def test_validate_output_path_must_stay_under_docs_assets_infographics(tmp_path: Path) -> None:
+    good = tmp_path / "docs/assets/infographics/pr-42.webp"
+    bad = tmp_path / "docs/assets/pr-42.webp"
+
+    assert generate_infographic.validate_output_path(good, repo_root=tmp_path) == good
+    with pytest.raises(ValueError, match="docs/assets/infographics"):
+        generate_infographic.validate_output_path(bad, repo_root=tmp_path)
@@ -14,6 +14,28 @@ def _is_postgres() -> bool:
    return os.environ.get("BASIC_MEMORY_TEST_POSTGRES", "").lower() in ("1", "true", "yes")


+async def _create_embeddings_stub(project_service: ProjectService) -> None:
+    """Create a minimal search_vector_embeddings stub so vector_tables_exist is True.
+
+    Test fixtures run with semantic search disabled, so the real vec0/pgvector
+    embeddings table is never created. get_embedding_status only probes table
+    existence and joins on chunk_id (rowid on SQLite), so a plain table suffices.
+    """
+    await project_service.repository.execute_query(
+        text(
+            "CREATE TABLE IF NOT EXISTS search_vector_embeddings (  chunk_id INTEGER PRIMARY KEY)"
+        ),
+        {},
+    )
+
+
+async def _drop_embeddings_stub(project_service: ProjectService) -> None:
+    """Drop the stub table to avoid polluting subsequent tests."""
+    await project_service.repository.execute_query(
+        text("DROP TABLE IF EXISTS search_vector_embeddings"), {}
+    )
+
+
@pytest.mark.asyncio
 async def test_embedding_status_semantic_disabled(project_service: ProjectService, test_project):
    """When semantic search is disabled, return minimal status with zero counts."""
@@ -69,7 +91,9 @@ async def test_embedding_status_entities_without_chunks(
    project_service: ProjectService, test_graph, test_project
 ):
    """When entities have search_index rows but no chunks, recommend reindex."""
-    # search_vector_chunks table is created by the test fixture (empty)
+    # search_vector_chunks comes from Base.metadata; the embeddings table needs a stub
+    # because fixtures run with semantic search disabled.
+    await _create_embeddings_stub(project_service)
    with patch.object(
        type(project_service),
        "config_manager",
@@ -79,6 +103,8 @@ async def test_embedding_status_entities_without_chunks(
    ):
        status = await project_service.get_embedding_status(test_project.id)

+    await _drop_embeddings_stub(project_service)
+
    assert status.semantic_search_enabled is True
    assert status.vector_tables_exist is True
    # test_graph creates entities indexed in search_index, but no vector chunks
@@ -159,6 +185,10 @@ async def test_embedding_status_handles_sqlite_vec_unavailable(
    if _is_postgres():
        pytest.skip("sqlite-vec unavailable handling is SQLite-specific.")

+    # Both vector tables must exist so the status check reaches the vec query;
+    # fixtures run with semantic search disabled, so stub the embeddings table.
+    await _create_embeddings_stub(project_service)
+
    # scalar_vec_query returns None when the extension can't be loaded on this
    # Python build (e.g. the python.org macOS interpreter). Simulate that here.
    async def _vec_query_unavailable(query, params=None):
@@ -178,6 +208,8 @@ async def test_embedding_status_handles_sqlite_vec_unavailable(
        ):
            status = await project_service.get_embedding_status(test_project.id)

+    await _drop_embeddings_stub(project_service)
+
    assert status.semantic_search_enabled is True
    assert status.total_indexed_entities > 0
    assert status.vector_tables_exist is False
@@ -272,6 +304,9 @@ async def test_embedding_status_excludes_stale_entity_ids(
    # Include 'id' column — required NOT NULL on Postgres (regular table),
    # ignored on SQLite (FTS5 virtual table where id is UNINDEXED).
    stale_entity_id = 999999
+    # Both vector tables must exist to reach the stale-filtered count queries;
+    # fixtures run with semantic search disabled, so stub the embeddings table.
+    await _create_embeddings_stub(project_service)
    await project_service.repository.execute_query(
        text(
            "INSERT INTO search_index "
@@ -1248,6 +1248,78 @@ async def test_index_entity_multiple_categories_same_content(
    assert len(results) >= 2


+@pytest.mark.asyncio
+async def test_index_entity_long_observations_shared_prefix_both_searchable(
+    search_service, session_maker, test_project
+):
+    """Regression test for issue #909: truncated permalink collisions drop observations.
+
+    Observation permalinks truncate content to 200 chars (PostgreSQL btree limit),
+    so two distinct observations of the same category sharing a 200-char prefix
+    collided on the same synthetic permalink and the second was silently skipped
+    during indexing. Both must be independently searchable.
+    """
+    from basic_memory.repository import EntityRepository, ObservationRepository
+    from datetime import datetime
+
+    entity_repo = EntityRepository(session_maker, project_id=test_project.id)
+    obs_repo = ObservationRepository(session_maker, project_id=test_project.id)
+
+    entity_data = {
+        "title": "Long Observation Collision Entity",
+        "note_type": "note",
+        "entity_metadata": {},
+        "content_type": "text/markdown",
+        "file_path": "test/long-obs-collision.md",
+        "permalink": "test/long-obs-collision",
+        "project_id": test_project.id,
+        "created_at": datetime.now(),
+        "updated_at": datetime.now(),
+    }
+    entity = await entity_repo.create(entity_data)
+
+    # Identical for the first 210 chars (beyond the 200-char truncation point),
+    # differing only in the trailing unique marker
+    shared_prefix = "x" * 210
+    await obs_repo.create(
+        {
+            "entity_id": entity.id,
+            "category": "note",
+            "content": f"{shared_prefix} ALPHA_UNIQUE_MARKER",
+        }
+    )
+    await obs_repo.create(
+        {
+            "entity_id": entity.id,
+            "category": "note",
+            "content": f"{shared_prefix} BETA_UNIQUE_MARKER",
+        }
+    )
+
+    # Reload entity with observations (get_by_permalink eagerly loads observations)
+    entity = await entity_repo.get_by_permalink("test/long-obs-collision")
+    assert entity is not None
+    assert len(entity.observations) == 2
+
+    # Distinct content must produce distinct permalinks despite the shared prefix
+    permalinks = {obs.permalink for obs in entity.observations}
+    assert len(permalinks) == 2
+
+    await search_service.index_entity(entity, content="")
+
+    # The second observation must be findable by its own unique marker
+    results = await search_service.search(
+        SearchQuery(text="BETA_UNIQUE_MARKER", entity_types=[SearchItemType.OBSERVATION])
+    )
+    assert any("BETA_UNIQUE_MARKER" in (r.content_snippet or "") for r in results)
+
+    # The first observation must remain findable as well
+    results = await search_service.search(
+        SearchQuery(text="ALPHA_UNIQUE_MARKER", entity_types=[SearchItemType.OBSERVATION])
+    )
+    assert any("ALPHA_UNIQUE_MARKER" in (r.content_snippet or "") for r in results)
+
+
 # Tests for NUL byte stripping


@@ -1312,6 +1384,21 @@ async def test_reindex_vectors(search_service, session_maker, test_project, monk

    entity_repo = EntityRepository(session_maker, project_id=test_project.id)

+    # Test fixtures disable semantic search, and delete_stale_vector_rows is the one call
+    # in this flow that requires the semantic stack — stub it so the test exercises the
+    # reindex wiring (id collection, batch call, stats mapping) without embeddings.
+    # raising=False: the method is SQLite-only; the Postgres purge path never calls it,
+    # so on Postgres this just attaches an unused attribute.
+    async def _noop_delete_stale_vector_rows() -> None:
+        return None
+
+    monkeypatch.setattr(
+        search_service.repository,
+        "delete_stale_vector_rows",
+        _noop_delete_stale_vector_rows,
+        raising=False,
+    )
+
    # Create some entities
    created_entity_ids: list[int] = []
    for i in range(3):
@@ -1382,6 +1469,22 @@ async def test_reindex_vectors_no_callback(
    from datetime import datetime

    entity_repo = EntityRepository(session_maker, project_id=test_project.id)
+
+    # Test fixtures disable semantic search, and delete_stale_vector_rows is the one call
+    # in this flow that requires the semantic stack — stub it so the test exercises the
+    # reindex wiring without embeddings.
+    # raising=False: the method is SQLite-only; the Postgres purge path never calls it,
+    # so on Postgres this just attaches an unused attribute.
+    async def _noop_delete_stale_vector_rows() -> None:
+        return None
+
+    monkeypatch.setattr(
+        search_service.repository,
+        "delete_stale_vector_rows",
+        _noop_delete_stale_vector_rows,
+        raising=False,
+    )
+
    entity = await entity_repo.create(
        {
            "title": "No Callback Entity",
@@ -6,6 +6,8 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Any, cast

+import os
+
 import pytest

 from basic_memory.config import ProjectConfig, BasicMemoryConfig
@@ -388,6 +390,11 @@ modified: 2024-01-01


@pytest.mark.asyncio
+@pytest.mark.skipif(
+    os.environ.get("CI") == "true",
+    reason="#940: intermittent batch-indexing race leaves a relation unresolved under CI "
+    "concurrency; quarantined pending root-cause, still runs locally",
+)
 async def test_sync_entity_circular_relations(
    sync_service: SyncService, project_config: ProjectConfig
 ):
@@ -55,3 +55,76 @@ def test_codex_plugin_docs_explain_global_install_and_repo_mapping() -> None:
    assert "codex plugin add codex@basic-memory-local" in readme
    assert "Plugin installation is user-level in Codex" in readme
    assert "Each repository still needs its own `.codex/basic-memory.json`" in readme
+
+
+def test_infographics_skill_keeps_weekly_contract_and_bm_style_pool() -> None:
+    repo_root = Path(__file__).resolve().parents[1]
+    skill = (repo_root / ".agents/skills/infographics/SKILL.md").read_text(encoding="utf-8")
+    style_balance = (
+        repo_root / ".agents/skills/infographics/references/style-balance.md"
+    ).read_text(encoding="utf-8")
+    prompt_blueprint = (
+        repo_root / ".agents/skills/infographics/references/prompt-blueprint.md"
+    ).read_text(encoding="utf-8")
+    skill_flat = " ".join(skill.split())
+
+    assert "Weekly image" in skill
+    assert "2-Week Retro window" in skill
+    assert "docs/assets/infographics/<year>-w<start-week>-w<end-week>.webp" in skill
+    assert (
+        "docs/assets/infographics/<start-year>-w<start-week>-<end-year>-w<end-week>.webp" in skill
+    )
+    assert "computer science college textbooks" in skill
+    assert "classic literature subjects" in skill
+    assert "Metal, Hard Rock, Punk, techno, soul, reggae" in skill
+    assert "Star Wars inspired knockoff" in skill
+    assert "WWII propaganda posters" in skill
+    assert "Italian movie posters" in skill
+    assert "space exploration and astronomy" in skill
+    assert "paintings" in skill
+    assert "abstract painting" in skill
+    assert "classical landscape" in skill
+    assert "Remington-inspired" in skill
+    assert "Rembrandt-inspired" in skill
+    assert "classic black-and-white photography" in skill
+    assert "documentary" in skill
+    assert "editorial photo essay" in skill
+    assert "80's action movies" in skill
+    assert "practical explosions" in skill
+    assert "no direct actor likenesses" in skill
+    assert "poster, scene, tableau, cover image" in skill_flat
+    assert "image-first" in skill
+    assert "--print-prompt" in skill
+    assert "--dry-run" in skill
+    assert "--visual-format" not in skill
+    assert "--provenance-output" in skill
+    assert "BM_INFOGRAPHIC_PROVENANCE:start" in skill
+    assert "Image prompt sent to" not in skill
+    assert "revised prompt" not in skill
+    assert "star charts" in style_balance
+    assert "editorial scene" in style_balance
+    assert "painting, photograph" in style_balance
+    assert "copyrighted characters, logos, or named fictional universes" in skill
+    assert "retro game or classic app aesthetic" not in skill
+    assert "BM style category" in style_balance
+    assert "Chosen image form" in prompt_blueprint
+    assert "Chosen BM style category" in prompt_blueprint
+
+
+def test_pr_create_skill_documents_optional_infographic_theme_arg() -> None:
+    repo_root = Path(__file__).resolve().parents[1]
+    skill = (repo_root / ".agents/skills/pr-create/SKILL.md").read_text(encoding="utf-8")
+    skill_flat = " ".join(skill.split())
+
+    assert "## How To Use" in skill
+    assert "$pr-create" in skill
+    assert "<theme>" in skill
+    assert '$pr-create "Italian movie poster"' in skill
+    assert '$pr-create "80\'s action movies"' in skill
+    assert "<!-- BM_INFOGRAPHIC_THEME:start -->" in skill
+    assert "<!-- BM_INFOGRAPHIC_THEME:end -->" in skill
+    assert "<!-- BM_INFOGRAPHIC_PROVENANCE:start -->" in skill
+    assert "BM Bossbot Approval" in skill
+    assert "selected visual direction" in skill_flat
+    assert "never merges" in skill
+    assert "non-gating" in skill
@@ -10,6 +10,9 @@ from basic_memory.cli.commands.cloud.rclone_commands import (
    MIN_RCLONE_VERSION_EMPTY_DIRS,
    RcloneError,
    SyncProject,
+    TransferPlan,
+    _conflict_copy_name,
+    _parse_check_combined,
    bisync_initialized,
    check_rclone_installed,
    get_project_bisync_state,
@@ -17,27 +20,33 @@ from basic_memory.cli.commands.cloud.rclone_commands import (
    get_rclone_version,
    project_bisync,
    project_check,
+    project_copy,
+    project_copy_file,
+    project_diff,
    project_ls,
    project_sync,
+    project_transfer,
    supports_create_empty_src_dirs,
 )


 class _RunResult:
-    def __init__(self, returncode: int = 0, stdout: str = ""):
+    def __init__(self, returncode: int = 0, stdout: str = "", stderr: str = ""):
        self.returncode = returncode
        self.stdout = stdout
+        self.stderr = stderr


 class _Runner:
-    def __init__(self, *, returncode: int = 0, stdout: str = ""):
+    def __init__(self, *, returncode: int = 0, stdout: str = "", stderr: str = ""):
        self.calls: list[tuple[list[str], dict]] = []
        self._returncode = returncode
        self._stdout = stdout
+        self._stderr = stderr

    def __call__(self, cmd: list[str], **kwargs):
        self.calls.append((cmd, kwargs))
-        return _RunResult(returncode=self._returncode, stdout=self._stdout)
+        return _RunResult(returncode=self._returncode, stdout=self._stdout, stderr=self._stderr)


 def _assert_has_consistency_headers(cmd: list[str]) -> None:
@@ -78,6 +87,19 @@ def test_get_project_remote():
    assert get_project_remote(project, "my-bucket") == "basic-memory-cloud:my-bucket/research"


+def test_get_project_remote_uses_workspace_remote():
+    # Non-default/team workspaces route through their own tenant-scoped remote.
+    project = SyncProject(name="research", path="/research", remote_name="basic-memory-cloud-acme")
+    assert (
+        get_project_remote(project, "acme-bucket") == "basic-memory-cloud-acme:acme-bucket/research"
+    )
+
+
+def test_sync_project_remote_name_defaults_to_legacy_remote():
+    project = SyncProject(name="research", path="/research")
+    assert project.remote_name == "basic-memory-cloud"
+
+
 def test_get_project_remote_strips_app_data_prefix():
    project = SyncProject(name="research", path="/app/data/research")
    assert get_project_remote(project, "my-bucket") == "basic-memory-cloud:my-bucket/research"
@@ -562,3 +584,353 @@ def test_project_bisync_includes_no_preallocate_flag(tmp_path):

    cmd, _ = runner.calls[0]
    assert "--local-no-preallocate" in cmd
+
+
+# --- Directional transfer primitives (push / pull, issue #858) ---
+
+
+def test_parse_check_combined_classifies_lines():
+    output = "= same.md\n+ only-src.md\n- only-dst.md\n* differ.md\n! broken.md\n\n"
+    plan = _parse_check_combined(output)
+    assert plan.new == ["only-src.md"]
+    assert plan.dest_only == ["only-dst.md"]
+    assert plan.conflicts == ["differ.md"]
+    assert plan.errors == ["broken.md"]
+
+
+def test_parse_check_combined_handles_paths_with_spaces():
+    plan = _parse_check_combined("* notes/my file.md\n")
+    assert plan.conflicts == ["notes/my file.md"]
+
+
+def test_conflict_copy_name_inserts_marker_before_extension():
+    assert _conflict_copy_name("notes/x.md", "20260608-1030") == "notes/x.conflict-20260608-1030.md"
+    assert _conflict_copy_name("top.md", "S") == "top.conflict-S.md"
+
+
+def test_project_diff_pull_uses_remote_as_source(tmp_path):
+    runner = _Runner(returncode=1, stdout="+ a.md\n* b.md\n")
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    plan = project_diff(
+        project,
+        "my-bucket",
+        "pull",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, kwargs = runner.calls[0]
+    assert cmd[:2] == ["rclone", "check"]
+    # pull: cloud is the source so "+" files (only on source) come down to local
+    assert cmd[2] == "basic-memory-cloud:my-bucket/research"
+    assert Path(cmd[3]) == Path("/tmp/research")
+    assert "--combined" in cmd and cmd[cmd.index("--combined") + 1] == "-"
+    _assert_has_consistency_headers(cmd)
+    assert "--filter-from" in cmd
+    assert kwargs["capture_output"] is True
+    # rclone exits non-zero when files differ; we parse output rather than trust it
+    assert plan.new == ["a.md"]
+    assert plan.conflicts == ["b.md"]
+
+
+def test_project_diff_push_uses_local_as_source(tmp_path):
+    runner = _Runner(returncode=0, stdout="")
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    project_diff(
+        project,
+        "my-bucket",
+        "push",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert Path(cmd[2]) == Path("/tmp/research")
+    assert cmd[3] == "basic-memory-cloud:my-bucket/research"
+
+
+def test_project_copy_pull_new_only_adds_ignore_existing(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    result = project_copy(
+        project,
+        "my-bucket",
+        "pull",
+        overwrite=False,
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    assert result is True
+    cmd, _ = runner.calls[0]
+    assert cmd[:2] == ["rclone", "copy"]
+    assert cmd[2] == "basic-memory-cloud:my-bucket/research"
+    assert Path(cmd[3]) == Path("/tmp/research")
+    assert "--ignore-existing" in cmd
+    assert "--local-no-preallocate" in cmd
+    # new-only skips by existence, so no content comparison is needed
+    assert "--checksum" not in cmd
+
+
+def test_project_copy_pull_overwrite_omits_ignore_existing(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    project_copy(
+        project,
+        "my-bucket",
+        "pull",
+        overwrite=True,
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert "--ignore-existing" not in cmd
+    # overwrite compares by content so it matches hash-based conflict detection
+    assert "--checksum" in cmd
+
+
+def test_project_copy_push_uses_local_as_source(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    project_copy(
+        project,
+        "my-bucket",
+        "push",
+        overwrite=False,
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert Path(cmd[2]) == Path("/tmp/research")
+    assert cmd[3] == "basic-memory-cloud:my-bucket/research"
+
+
+def test_project_copy_file_pull_copyto_renames_on_dest(tmp_path):
+    runner = _Runner(returncode=0)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    project_copy_file(
+        project,
+        "my-bucket",
+        "pull",
+        "notes/dup.md",
+        "notes/dup.conflict-S.md",
+        run=runner,
+        is_installed=lambda: True,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert cmd[:2] == ["rclone", "copyto"]
+    assert cmd[2] == "basic-memory-cloud:my-bucket/research/notes/dup.md"
+    # Compare the local dest via Path so the assertion holds on Windows, where the
+    # local root renders with backslashes (rclone accepts the mixed separators).
+    assert Path(cmd[3]) == Path("/tmp/research/notes/dup.conflict-S.md")
+    # pull writes the conflict copy locally → must guard virtual-FS NUL padding
+    assert "--local-no-preallocate" in cmd
+
+
+def test_project_transfer_keep_both_copies_conflicts_then_additive(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=["a.md"], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    result = project_transfer(
+        project,
+        "my-bucket",
+        "pull",
+        plan,
+        strategy="keep-both",
+        conflict_suffix="S",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    assert result is True
+    # First a copyto for the conflict file, written beside the local copy...
+    first_cmd, _ = runner.calls[0]
+    assert first_cmd[:2] == ["rclone", "copyto"]
+    # Path comparison so this holds on Windows (backslash local root).
+    assert Path(first_cmd[3]) == Path("/tmp/research/dup.conflict-S.md")
+    # ...then an additive (new-only) copy that won't overwrite existing local files.
+    second_cmd, _ = runner.calls[1]
+    assert second_cmd[:2] == ["rclone", "copy"]
+    assert "--ignore-existing" in second_cmd
+
+
+def test_project_transfer_keep_cloud_on_pull_overwrites_local(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=[], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    project_transfer(
+        project,
+        "my-bucket",
+        "pull",
+        plan,
+        strategy="keep-cloud",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    # keep-cloud + pull → cloud (source) overwrites local (dest): no --ignore-existing,
+    # and --checksum so the overwrite decision matches the content-based conflict.
+    assert len(runner.calls) == 1
+    cmd, _ = runner.calls[0]
+    assert cmd[:2] == ["rclone", "copy"]
+    assert "--ignore-existing" not in cmd
+    assert "--checksum" in cmd
+
+
+def test_project_transfer_keep_local_on_push_overwrites_cloud(tmp_path):
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=[], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    project_transfer(
+        project,
+        "my-bucket",
+        "push",
+        plan,
+        strategy="keep-local",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert "--ignore-existing" not in cmd
+
+
+def test_project_diff_requires_local_path():
+    project = SyncProject(name="research", path="/research")
+    with pytest.raises(RcloneError):
+        project_diff(project, "my-bucket", "pull", is_installed=lambda: True)
+
+
+def test_project_diff_raises_on_fatal_check_error(tmp_path):
+    """A non-zero exit with no combined listing means the check failed, not 'no diffs'."""
+    runner = _Runner(returncode=7, stdout="", stderr="Failed to create file system: AccessDenied")
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    with pytest.raises(RcloneError) as exc_info:
+        project_diff(
+            project,
+            "my-bucket",
+            "pull",
+            run=runner,
+            is_installed=lambda: True,
+            filter_path=filter_path,
+        )
+
+    assert "AccessDenied" in str(exc_info.value)
+
+
+def test_project_diff_nonzero_with_differences_does_not_raise(tmp_path):
+    """Differences make rclone check exit non-zero, but that is expected — no raise."""
+    runner = _Runner(returncode=1, stdout="* changed.md\n")
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+
+    plan = project_diff(
+        project,
+        "my-bucket",
+        "pull",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    assert plan.conflicts == ["changed.md"]
+
+
+def test_project_transfer_keep_local_on_pull_preserves_local(tmp_path):
+    """keep-local + pull → local is the destination and must be preserved (--ignore-existing)."""
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=[], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    project_transfer(
+        project,
+        "my-bucket",
+        "pull",
+        plan,
+        strategy="keep-local",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert "--ignore-existing" in cmd
+    assert "--checksum" not in cmd
+
+
+def test_project_transfer_keep_cloud_on_push_preserves_cloud(tmp_path):
+    """keep-cloud + push → cloud is the destination and must be preserved (--ignore-existing)."""
+    runner = _Runner(returncode=0)
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=[], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    project_transfer(
+        project,
+        "my-bucket",
+        "push",
+        plan,
+        strategy="keep-cloud",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    cmd, _ = runner.calls[0]
+    assert "--ignore-existing" in cmd
+
+
+def test_project_transfer_keep_both_returns_false_on_copy_failure(tmp_path):
+    """A failed conflict-copy aborts the transfer before the additive pass."""
+    runner = _Runner(returncode=1)  # every rclone invocation fails
+    filter_path = _write_filter_file(tmp_path)
+    project = SyncProject(name="research", path="/research", local_sync_path="/tmp/research")
+    plan = TransferPlan(new=["a.md"], conflicts=["dup.md"], dest_only=[], errors=[])
+
+    result = project_transfer(
+        project,
+        "my-bucket",
+        "pull",
+        plan,
+        strategy="keep-both",
+        conflict_suffix="S",
+        run=runner,
+        is_installed=lambda: True,
+        filter_path=filter_path,
+    )
+
+    assert result is False
+    # Stopped after the first failed copyto — the additive copy never ran.
+    assert len(runner.calls) == 1
+    assert runner.calls[0][0][:2] == ["rclone", "copyto"]
@@ -323,6 +323,7 @@ dev = [
    { name = "pytest-cov" },
    { name = "pytest-mock" },
    { name = "pytest-testmon" },
+    { name = "pytest-timeout" },
    { name = "pytest-xdist" },
    { name = "ruff" },
    { name = "testcontainers" },
@@ -390,6 +391,7 @@ dev = [
    { name = "pytest-cov", specifier = ">=4.1.0" },
    { name = "pytest-mock", specifier = ">=3.12.0" },
    { name = "pytest-testmon", specifier = ">=2.2.0" },
+    { name = "pytest-timeout", specifier = ">=2.4.0" },
    { name = "pytest-xdist", specifier = ">=3.0.0" },
    { name = "ruff", specifier = ">=0.1.6" },
    { name = "testcontainers", extras = ["postgres"], specifier = ">=4.0.0" },
@@ -3071,6 +3073,18 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/61/55/ebb3c2f59fb089f08d00f764830d35780fc4e4c41dffcadafa3264682b65/pytest_testmon-2.2.0-py3-none-any.whl", hash = "sha256:2604ca44a54d61a2e830d9ce828b41a837075e4ebc1f81b148add8e90d34815b", size = 25199, upload-time = "2025-12-01T07:30:23.623Z" },
 ]

+[[package]]
+name = "pytest-timeout"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/82/4c9ecabab13363e72d880f2fb504c5f750433b2b6f16e99f4ec21ada284c/pytest_timeout-2.4.0.tar.gz", hash = "sha256:7e68e90b01f9eff71332b25001f85c75495fc4e3a836701876183c4bcfd0540a", size = 17973, upload-time = "2025-05-05T19:44:34.99Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl", hash = "sha256:c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2", size = 14382, upload-time = "2025-05-05T19:44:33.502Z" },
+]
+
 [[package]]
 name = "pytest-xdist"
 version = "3.8.0"
Author	SHA1	Message	Date
phernandez	513fef79c5	test(sync): quarantine circular-relations test in CI pending #940 The batch-indexing race has now flaked three CI rounds today. Skipped under CI only (still runs locally); #940 tracks the root cause. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-10 12:10:01 -05:00
phernandez	afa694ba8d	fix(ci): anchor paged-status test fake on the &page separator 'page=1' substring-matched 'per_page=100', so the fake served page 1 forever and the pagination loop hung — caught by the new 120s test timeout on every CI leg. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-10 11:12:53 -05:00
phernandez	8668118f78	fix(ci): fail hung tests after 120s instead of stalling the job Unit legs intermittently hang mid-suite (FastMCP/asyncpg cleanup-hang family) and sit until the runner gives up, eating 20+ minutes per occurrence. pytest-timeout turns a hang into a fast failure with a stack dump naming the test. Signed-off-by: phernandez <paul@basicmachines.co> (cherry picked from commit `0295cd9d56`)	2026-06-10 10:35:55 -05:00
Paul Hernandez	e81cdc2980	Merge branch 'main' into fix/bossbot-thread-gate	2026-06-10 09:44:36 -05:00
phernandez	d8c9156ffd	feat(ci): make BM Bossbot a deterministic merge gate Remove the Codex LLM review and the per-PR image job — both spent API tokens on every Bossbot run and the connector review already covers code review. The gate is now fully deterministic: Tests passed for the head SHA, non-draft, trusted author, zero unresolved review threads. Prompt/schema files removed; guard tests updated to forbid openai/codex-action and image generation from reappearing. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-10 09:43:47 -05:00
phernandez	291a8085ef	fix(ci): paginate commit statuses when restoring prior bossbot approval The recheck path posts a status per review-thread event, so a busy PR can exceed one page of statuses and the original approval record falls off page one — resolving the last thread would then never restore it. Page through all statuses for the BM Bossbot context. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-10 09:18:29 -05:00
Paul Hernandez	49041a5168	docs(skills): fix npx skill install docs and ignore docs assets (#927 ) Refs #930 docs cleanup; adds docs/assets to gitignore. Signed-off-by: phernandez <paul@basicmemory.com>	2026-06-10 01:30:50 -05:00
Paul Hernandez	8cbe1634b6	fix(cli): don't let bm cloud setup overwrite an existing rclone remote (#923 ) Closes #922 Signed-off-by: phernandez <paul@basicmemory.com>	2026-06-10 01:02:43 -05:00
Paul Hernandez	c4b651f5b0	fix(mcp): accept page/page_size in read_note for parity with sibling tools (#933 ) Closes #883 Refs #882 Signed-off-by: phernandez <paul@basicmemory.com>	2026-06-10 00:03:22 -05:00
phernandez	33fdd3d44e	test(ci): scope bossbot untrusted-head guard to dangerous PR fields The guard banned any github.event.pull_request reference, but the recheck job legitimately needs the numeric PR id. Allow exactly .number and keep forbidding head checkout and attacker-controlled string fields. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 23:31:14 -05:00
phernandez	ef6c47e674	feat(ci): ground PR images in delivery context, not just title/description Mirror the ProjectUpdateContext shape the basic-memory.yml capture flow collects: the image prompt now receives a compact change-shape digest — labels, linked issues with titles, commit subjects (the PR's narrative arc), and a churn-ranked changed-files summary with totals — from a single 'gh pr view --json' call passed as --pr-context-file (replacing --pr-title/--pr-body-file). The digest is explicitly context, not captions: the prompt forbids rendering paths, stats, issue numbers, or commit subjects verbatim in the image. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 23:12:18 -05:00
phernandez	f9c3baf5b9	test(ci): satisfy ty narrowing in graphql pagination fake Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 23:04:35 -05:00
phernandez	24abf11dab	fix(ci): block BM Bossbot approval on unresolved review threads; theme PR images on PR content Two BM Bossbot fixes: 1. Unresolved review threads now block approval. The review prompt only sees metadata+diff, so an approve verdict said nothing about outstanding feedback — #932 merged with two open Codex P2 threads. finalize now counts unresolved reviewThreads via GraphQL and fails the status when any remain. A new recheck command, triggered by pull_request_review / review_comment / review_thread events, flips the status to failure when feedback arrives after approval and restores a previously earned approval for the same head SHA once every thread is resolved. Review and recheck jobs use separate job-level concurrency groups so neither cancels the other. 2. PR images depict the PR's content, not the review outcome. The image prompt previously used the BM Bossbot review summary (verdict/status) as its only source material, so every image rendered an APPROVED stamp. The prompt now sources the PR title and the author's own description (managed bot blocks stripped) and explicitly bans approval stamps, verdict wording, badges, checkmarks, and Bossbot branding. Theme selection seeds on PR number+title for stability across re-reviews. Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 23:02:41 -05:00
Paul Hernandez	ca9a4d9c12	fix(mcp): split comma-separated tags in search_notes tags param (#932 ) Closes #910 Signed-off-by: phernandez <paul@basicmemory.com>	2026-06-09 22:23:26 -05:00
Paul Hernandez	aa9594d82a	perf(ci): disable semantic search in default test fixtures (#938 ) Disable the silently-on semantic embedding stack in default test fixtures and deselect on-demand benchmarks from CI int jobs. int SQLite 337s -> 110s, Postgres unit ~25min -> ~13min. Signed-off-by: phernandez <paul@basicmemory.com>	2026-06-09 21:55:21 -05:00
Paul Hernandez	93494b8c13	ci(ci): gate bossbot on passing tests (#937 ) Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 20:47:34 -05:00
Paul Hernandez	93ed34001b	fix(core): disambiguate truncated observation permalinks to prevent index collisions (#931 ) Signed-off-by: phernandez <paul@basicmachines.co> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-09 20:20:46 -05:00
Paul Hernandez	ec94feb6a4	Merge branch 'main' into codex/fix-bossbot-assets-publish	2026-06-09 19:23:27 -05:00
Paul Hernandez	831b9141a5	ci(ci): use pytestmon and Depot runners (#928 ) Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 19:20:08 -05:00
phernandez	2de19713f6	fix(ci): make BM Bossbot asset cleanup idempotent Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 19:14:13 -05:00
phernandez	79fcfbce6a	fix(ci): restrict BM Bossbot to trusted PR authors Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 17:16:49 -05:00
phernandez	3d22ba3004	fix(ci): harden BM Bossbot finalization Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 16:32:06 -05:00
phernandez	62229d9d0a	fix(ci): address BM Bossbot PR feedback Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 15:55:36 -05:00
phernandez	03ba268cb1	feat(ci): add BM Bossbot PR gate Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-09 15:18:40 -05:00
Paul Hernandez	de53e0ecc5	feat(cli): per-workspace rclone remotes for Team push/pull (#920 ) Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-08 17:39:37 -05:00
Paul Hernandez	4128cac9ab	docs(core): add Basic Machines agent style guidance (#921 ) Signed-off-by: phernandez <paul@basicmachines.co>	2026-06-08 17:09:50 -05:00
Paul Hernandez	9b53d7863f	feat(cli): add Team-safe cloud push/pull and gate sync to Personal workspaces (#917 ) Adds additive, git-style `bm cloud push`/`pull` that are safe on shared Team workspaces (never delete on the destination; conflicts abort by default with `--on-conflict {fail\|keep-local\|keep-cloud\|keep-both}`), and gates the destructive `bm cloud sync`/`bisync` mirrors to Personal workspaces. Closes #858. Longer-term Team-safe reconciler tracked in #862; workspace-scoped mount info (Codex P1) tracked as a follow-up.	2026-06-08 14:08:49 -05:00