Change Requests
Propose, review, and merge changes to your team's shared knowledge base through a structured review workflow.
Change Requests
What is a change request?
Your team has a shared knowledge base called team memory — a collection of Markdown files under team/memory/. These might be guides, runbooks, decision logs, meeting notes, or any other documents your team keeps in Synap.
Because team memory is shared, changes to it go through a review step before they appear for everyone. A change request (CR) is how you propose a change: you bundle one or more edited files, describe what you changed and why, and submit them for a teammate to review. Once approved, you merge the CR and the changes take effect.
If you have used GitHub or GitLab, this is the same idea as a pull request — but you never see raw Git. Synap handles the version tracking automatically.
The local-first model
When you edit a file under team/memory/, the change is saved as a draft on your device inside personal/_workspace/. The canonical file — the one other team members see — is not touched until you open a change request and it is merged.
This means:
- You can edit freely without disturbing your teammates.
- Your draft survives app restarts and syncs across your own devices.
- Nothing is lost if you close the app before submitting.
Workflow
1. Edit a file under team/memory/
Open a file under Team Memory in the sidebar and make your changes in the editor. The file banner shows "Draft — not shared yet" to remind you the change is local.
2. Open the Workspace
Go to Mind → Changes → Workspace in the top menu (or press the keyboard shortcut shown in the sidebar). The Workspace panel lists all files you have edited that have not yet been submitted.
3. Select drafts and open a change request
Check the files you want to include in this change request. You can submit all drafts together or split them into separate CRs if they are unrelated changes.
Click Open change request.
4. Fill in the details
- Title (required): a short summary of what you changed. Example: "Update Q2 priorities and OKRs."
- Description (optional): context for the reviewer — what changed, why, and any relevant links.
- Reviewer (optional): pick a teammate to review. If you leave this empty, any team admin can review.
Click Submit.
5. Wait for review
The CR appears in your Changes inbox with status "In review." Your selected reviewer receives a notification.
6. Reviewer approves → you merge
Once a reviewer approves the CR, its status changes to "Approved." You (or any team admin) can then click Merge. The proposed content is written to the canonical team/memory/ files and immediately visible to the whole team.
Quick change
If your role has self-approve permission (usually owners and admins), you can skip the review step entirely. Instead of "Open change request," click Save quick change in the Workspace. This bundles your drafts, approves them automatically, and merges in one click.
Use this for routine, low-risk edits — typo fixes, adding a meeting note — where a review would add friction without adding safety.
Reviewing a change request
When a teammate asks you to review a CR, you receive a notification in the Changes inbox.
Steps
- Open the inbox from the sidebar (Changes section).
- Click the CR title to open the detail view.
- Click View diff to see exactly what changed in each file — green lines were added, red lines were removed.
- Choose an action:
- Approve — the CR is approved; the author can now merge.
- Request changes — write a short explanation of what needs to change before you will approve. A note is required.
After you request changes, the CR moves back to "Changes requested" status. The author can update their drafts and resubmit for review.
Common scenarios
"Base advanced" banner
If someone else merged a change to one of the same files while your CR was open, you will see a "Base advanced" banner on the diff for that file. This means the current HEAD has moved past the version your draft was based on.
What to do: review the diff carefully to make sure your changes still apply correctly, then re-target the affected files. Discard and re-edit the file from the current HEAD if the conflict is complex.
"Source file deleted" banner
The canonical file was deleted (or renamed by someone else) after you opened your draft. Your draft still contains your proposed content, but there is no longer a HEAD file to diff against.
Options:
- Discard draft: abandon your changes for that file.
- Open a CR to restore it: submit the file as a new file at the same path, effectively recreating it with your content.
"Renamed" banner
The canonical file was renamed after you opened your draft. Synap treats the original path as orphaned. Same options as "Source file deleted" above.
Limits
| Limit | Value |
|---|---|
| Maximum files per CR | 100 |
| Maximum total size per CR | 10 MB (combined draft content) |
If your change exceeds these limits, split it into multiple CRs.
What is NOT covered by change requests
personal/ — Your personal files (notes, focus documents, canvas boards) are private to you. They do not require a CR and are never visible to teammates through the CR workflow.
team/design/, team/publish/, team/agents/, team/brand/, team/set/ — Design assets, published content, agent workflows, branding, and set assets are free-write. They sync directly without a change request workflow.