SharedContext is a scoped workspace of Markdown files, not a catalog of special knowledge types. A Space can contain several projects; each project keeps its own Context. Start with a few clear documents and one index inside the relevant scope. Add folders only when the material earns structure.
Choose how far the Context should travel
project: decisions and state specific to one project. This is the default, and one project's Context is isolated from its siblings.space: conventions and patterns that genuinely apply across the Space and its projects.personal: private notes that should follow the user across workspaces.
Use index.md as a first screen
A folder's index.md is its narrative home screen — rules, decisions, roadmap, and must-read pointers, written as prose, never a list of child documents. session_open always shows it first, then automatically appends a generated list of every document in that scope (path — description, taken from each document's own one-line description) right after it — so never hand-write a per-document entry into index.md; it would only duplicate what session_open already attaches.
Because session_open injects the narrative every session, keep it small. If it grows, move detail into a linked document and keep only the pointer in index.md.
An index is a starting point, not proof that every sentence is current or user-confirmed. Label proposals, assumptions, and open questions, and link to the document that records the source and status.
Keep detail in separate documents
Case-specific detail belongs in its own file — write it with a clear one-line description. session_open's auto-generated list surfaces it, so no manual link from index.md is required. When a topic grows, it can become a folder with its own index.md.
index.md
decisions/pricing.md
research/team-demand.md
work/active-scope.md
Check consistency after a write
After a write that changes a decision or state, check three places: this scope's index.md narrative (when it references the topic), any document that narrative points to on the same topic, and any document the edited one explicitly links. That is the boundary on purpose — a full sweep of every document is out of scope. If something disagrees with what you just wrote, either update it, mark it superseded, or — when you cannot tell which side is current — record it as an open conflict rather than overwriting without evidence.
Keep one active project scope
Unless the project already declares another source of truth, use work/active-scope.md for the current project scope. Draft it from existing Context rather than asking the user to fill in a blank template. It covers the current goal and state, valid decisions and constraints, active and excluded scope, next actions, open questions, and completion criteria.
Use a lifecycle status of draft, active, completed, or superseded. The Agent may prepare a draft, but only explicit human approval can make the goal, active scope, and completion criteria active. When the scope is completed or replaced, update this document, and if the project index.md narrative names this scope, update that mention too so it points only to current work.
Do not over-structure up front
A few documents with clear paths are better than an empty hierarchy. Let the shape of the work reveal the folders it needs.
Update the old decision
When a decision changes, edit the current document instead of adding a contradictory answer. Revision history preserves what came before without leaving stale guidance in active Context.