docs: add team usage guide#331
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page describing how teams should use Engram collaboratively, focusing on the meaning of scope: project vs scope: personal, recommended language conventions for shared memory, and guidance around syncing across teammates/devices. This fits into the broader docs set by filling the “team adoption” gap called out in #305 and making the guide discoverable from the main docs entry points.
Changes:
- Added
docs/TEAM-USAGE.mdwith a scope mental model, examples, language convention, and workflow guidance. - Linked the new guide from the top-level
README.mddocs nav and quick-start area. - Added the guide to the “For other docs” table in
DOCS.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds navigation + a quick pointer to the new team usage guide. |
| docs/TEAM-USAGE.md | New team-oriented guide covering scope, language convention, and sync workflow concepts. |
| DOCS.md | Adds the new guide to the docs index table for discoverability. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Alan-TheGentleman
left a comment
Alan-TheGentleman
left a comment
There was a problem hiding this comment.
Thanks for recreating this. The guide fills the right docs gap, but I would not merge it yet.
Two things need fixing first. Add the required type:docs label so the PR passes validation. More importantly, clarify that scope: personal is not currently a sync boundary: project sync exports by project/session association, not by excluding personal scope, so private notes can still replicate if they live in a shared enrolled project.
Once that wording is corrected, this should be good to merge.
|
Addressed the sync clarification in What changed:
I also attempted to add the required |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Ready for review! |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* docs: add team usage guide Adds docs/TEAM-USAGE.md covering the scope mental model (project vs personal), the lingua franca convention for shared memory, and the sync behavior teams actually get today. Honest about the current contract: scope filters search and context reads but does not filter sync. Both scopes leave the machine when the project is enrolled. Documents two workarounds (separate project name or no enrollment) and flags scope-aware sync as a deliberate future design decision. Linked from DOCS.md, the README nav, and the mem_save scope parameter description so the guide is discoverable from the obvious entry points. Closes #305 * docs(team-usage): clarify sync operates by project/session association per #331 review --------- Co-authored-by: Alan Buscaglia <gentlemanprogramming@gmail.com>
🔗 Linked Issue
Closes #305
🏷️ PR Type
type:bug— Bug fixtype:feature— New featuretype:docs— Documentation onlytype:refactor— Code refactoring (no behavior change)type:chore— Maintenance, dependencies, toolingtype:breaking-change— Breaking change📝 Summary
scope: projectvsscope: personal.README.mdandDOCS.mdso teams can find it quickly.📂 Changes
docs/TEAM-USAGE.mdREADME.mdDOCS.md🧪 Test Plan
go test ./...go test -tags e2e ./internal/server/...Manual verification:
README.mdandDOCS.md.🤖 Automated Checks
These run automatically and all must pass before merge:
Closes #N/Fixes #N/Resolves #Nstatus:approvedlabeltype:*labelgo test ./...passesgo test -tags e2e ./internal/server/...passes✅ Contributor Checklist
Closes #N)type:*label to this PRgo test ./...go test -tags e2e ./internal/server/...Co-Authored-Bytrailers in commits💬 Notes for Reviewers