Use project-prefixed keys in the README, usage guide, and project-init docs

README.md

@@ -18,9 +18,9 @@ Deploy DevBrain once and every project you work on shares the same knowledge sto
 
 ```
 # Morning session — three projects, three tool calls
-GetDocument(key="state:current", project="acme-platform")
-GetDocument(key="state:current", project="devbrain")
-GetDocument(key="state:current", project="client-abc")
+GetDocument(key="acme-platform:state:current", project="acme-platform")
+GetDocument(key="devbrain:state:current", project="devbrain")
+GetDocument(key="client-abc:state:current", project="client-abc")
 ```
 
 Compare that to alternatives:
@@ -331,12 +331,14 @@ DevBrain is only as useful as the context your AI tools actually load. The recom
 
 At the start of every session, load project context from DevBrain:
 
-1. GetDocument(key="state:current", project="{your-project}")
-2. If a sprint is active: GetDocument(key="sprint:{sprint-name}", project="{your-project}")
+1. GetDocument(key="{your-project}:state:current", project="{your-project}")
+2. If a sprint is active: GetDocument(key="{your-project}:sprint:{sprint-name}", project="{your-project}")
 
 Before ending a session, write back any significant changes:
-- UpsertDocument key="state:current" if project state changed
-- UpsertDocument key="sprint:{name}" if sprint progress changed
+- UpsertDocument key="{your-project}:state:current" if project state changed
+- UpsertDocument key="{your-project}:sprint:{name}" if sprint progress changed
+
+Every key starts with the project name, and every call also passes the project.
 
 DevBrain is the canonical source of truth. Do not ask the user to upload
 files or paste context — read it directly from DevBrain.
@@ -387,7 +389,7 @@ Example:
 
 ```text
 PreviewEditDocument(
-  key="state:current",
+  key="devbrain:state:current",
   project="devbrain",
   oldText="Status: draft",
   newText="Status: in progress"
@@ -396,7 +398,7 @@ PreviewEditDocument(
 
 ```text
 ApplyEditDocument(
-  key="state:current",
+  key="devbrain:state:current",
   project="devbrain",
   oldText="Status: draft",
   newText="Status: in progress",
@@ -432,15 +434,18 @@ Pick Append when the doc grows over time. Pick Chunked when you already have the
 
 Documents are organized by key prefix. These conventions are recommended but not enforced:
 
-Keys use colon as the separator (e.g. `sprint:license-sync`). **Writes** (`UpsertDocument`, `AppendDocument`, `UpsertDocumentChunked`) reject keys containing `/` with a "did you mean" error suggesting the colon form. **Reads** (`GetDocument`, `ListDocuments`, `SearchDocuments`) and `DeleteDocument` continue to accept slash keys so legacy data and cleanup operations keep working.
+A key identifies one document across the whole store; `project` filters reads but isn't part of a document's identity. Start every project document's key with its project name (for example `acme-platform:state:current`), and still pass `project` on every call. Unprefixed keys belong to the `default` project, which holds general DevBrain material such as `ref:devbrain-usage`.
+
+Keys use colon as the separator (e.g. `acme-platform:sprint:license-sync`). **Writes** (`UpsertDocument`, `AppendDocument`, `UpsertDocumentChunked`) reject keys containing `/` with a "did you mean" error suggesting the colon form. **Reads** (`GetDocument`, `ListDocuments`, `SearchDocuments`) and `DeleteDocument` continue to accept slash keys so legacy data and cleanup operations keep working.
 
 | Prefix | Use |
 |--------|-----|
-| `sprint:{name}` | Sprint specs, e.g. `sprint:license-sync` |
-| `state:current` | Current project state document |
-| `arch:{name}` | Architecture docs |
-| `decision:{name}` | Architecture decision records |
-| `ref:{name}` | Reference material, infra constants |
+| `{project}:sprint:{name}` | Sprint specs, e.g. `acme-platform:sprint:license-sync` |
+| `{project}:state:current` | Current project state document |
+| `{project}:arch:{name}` | Architecture docs |
+| `{project}:decision:{name}` | Architecture decision records |
+| `{project}:ref:{name}` | Project reference material, infra constants |
+| `ref:{name}` | General DevBrain reference material in the `default` project |
 
 ## Local Development
 

docs/project-init.md

@@ -2,13 +2,13 @@
 
 When you start using DevBrain for a new project, seed it with a small set of canonical documents so every AI tool has enough context to be useful from the first prompt. This guide lists the recommended starter documents and what each should contain.
 
-All documents below are namespaced by the `project` parameter — pass the same project name consistently across every `UpsertDocument` and `GetDocument` call.
+A key identifies one document across the whole store, so start every key with the project name and pass the same `project` on every `UpsertDocument` and `GetDocument` call. The examples below use `{your-project}` as that name.
 
 ## Required
 
-### `state:current` — the living project snapshot
+### `{your-project}:state:current` — the living project snapshot
 
-The single most important document. Every AI session should start with `GetDocument(key="state:current", project="{your-project}")`. Keep it short enough to load cheaply, detailed enough to orient a new session without follow-up questions.
+The single most important document. Every AI session should start with `GetDocument(key="{your-project}:state:current", project="{your-project}")`. Keep it short enough to load cheaply, detailed enough to orient a new session without follow-up questions.
 
 Recommended sections:
 
@@ -22,9 +22,9 @@ Update whenever any of those sections materially change. Treat it as the canonic
 
 ## When a sprint is active
 
-### `sprint:{name}` — the active sprint spec
+### `{your-project}:sprint:{name}` — the active sprint spec
 
-Create one per sprint, keyed by a short slug (e.g. `sprint:license-sync`). Load it at session start whenever work on that sprint is in flight.
+Create one per sprint, keyed by a short slug (e.g. `{your-project}:sprint:license-sync`). Load it at session start whenever work on that sprint is in flight.
 
 Recommended sections:
 
@@ -38,17 +38,17 @@ When the sprint ends, leave the document in place as a historical record — don
 
 ## Recommended
 
-### `arch:overview` — high-level architecture
+### `{your-project}:arch:overview` — high-level architecture
 
-A stable document describing the system's shape: major components, data flow, external dependencies, deployment topology. Updated infrequently — only when the architecture actually changes. Keep it short; link to `decision:{name}` documents for the reasoning behind specific choices.
+A stable document describing the system's shape: major components, data flow, external dependencies, deployment topology. Updated infrequently — only when the architecture actually changes. Keep it short; link to `{your-project}:decision:{name}` documents for the reasoning behind specific choices.
 
 ## Seeding a new project
 
 A minimal first-day setup:
 
 ```
-UpsertDocument(key="state:current",  project="{your-project}", content="...")
-UpsertDocument(key="arch:overview",  project="{your-project}", content="...")
+UpsertDocument(key="{your-project}:state:current",  project="{your-project}", content="...")
+UpsertDocument(key="{your-project}:arch:overview",  project="{your-project}", content="...")
 ```
 
-Add `sprint:{name}` documents as sprints start. Add `decision:{name}` and `ref:{name}` documents as the project accumulates history.
+Add `{your-project}:sprint:{name}` documents as sprints start. Add `{your-project}:decision:{name}` and `{your-project}:ref:{name}` documents as the project accumulates history.

docs/seed/ref-devbrain-usage.md

@@ -1,18 +1,20 @@
 # DevBrain — Usage Guide for AI Assistants
 
-## Important: Documents Are Scoped by Project
+## Important: Keys Include the Project
 
-DevBrain organizes documents by project. If a query returns no results, you are likely searching the wrong project scope.
+DevBrain organizes documents by project, but a key identifies one document across the whole store; `project` filters reads and isn't part of a document's identity.
 
-**Always specify the project parameter explicitly.** Use `default` for shared reference docs or quick sandboxing, and use named projects like `devbrain` for real project state.
+**Every key starts with its project name, and every call passes the project.** For example, use `key: "devbrain:state:current"` with `project: "devbrain"`. Two projects that both write an unprefixed `state:current` overwrite each other.
+
+Unprefixed keys belong to the `default` project, which holds general DevBrain instructions such as this guide (`ref:devbrain-usage`). Calls that omit `project` read and write `default`. If a query returns no results, check the key's project prefix and the project scope.
 
 ## Known Projects
 - `devbrain` — DevBrain's own documentation, architecture, sprint docs, backlog, known issues
 
 ## Session Startup Pattern
 For any project, the correct session startup is:
-1. `GetDocument(key="state:current", project="{project}")` — load current state
-2. If working a sprint: `GetDocument(key="sprint:{name}", project="{project}")` — load active spec
+1. `GetDocument(key="{project}:state:current", project="{project}")` — load current state
+2. If working a sprint: `GetDocument(key="{project}:sprint:{name}", project="{project}")` — load active spec
 3. Updates: write directly with `UpsertDocument` — no manual upload needed
 
 This replaces any manual file upload workflow. DevBrain is the canonical source.
@@ -33,7 +35,7 @@ ListDocuments(project: "devbrain")
 
 ### Get a specific document
 ```
-GetDocument(key: "state:current", project: "devbrain")
+GetDocument(key: "devbrain:state:current", project: "devbrain")
 ```
 
 ### Search across a project
@@ -47,7 +49,7 @@ Before importing or syncing a document, check whether the stored version is alre
 
 ### Quick existence and size check
 ```
-GetDocumentMetadata(key: "sprint:license-sync", project: "devbrain")
+GetDocumentMetadata(key: "devbrain:sprint:license-sync", project: "devbrain")
 ```
 Returns key, project, tags, updatedAt, updatedBy, contentHash (SHA-256), and contentLength (character count) — **without** the content body. Use this to:
 - Check if a document exists
@@ -56,7 +58,7 @@ Returns key, project, tags, updatedAt, updatedBy, contentHash (SHA-256), and con
 
 ### Confirm content matches before skipping a write
 ```
-CompareDocument(key: "sprint:license-sync", content: "...candidate text...", project: "devbrain")
+CompareDocument(key: "devbrain:sprint:license-sync", content: "...candidate text...", project: "devbrain")
 ```
 Returns `{ found, match, storedContentHash, candidateHash, ... }`. The server hashes the candidate content and compares against the stored hash. You can also pass a precomputed `contentHash` instead of raw content.
 
@@ -133,22 +135,26 @@ The server applies the diff:
 
 ## Key Conventions
 
+Every project key starts with the project name. Unprefixed keys are only for general DevBrain material in the `default` project.
+
 Keys use **colon** as the separator. Slash-separated keys (`sprint/foo`) still work for backward compatibility, but colons are the canonical, recommended convention — they signal "DevBrain key" at a glance and avoid being confused with file paths.
 
 | Prefix | Use |
 |---|---|
-| `sprint:{name}` | Sprint specs and retrospectives |
-| `state:current` | Current project state |
-| `arch:{name}` | Architecture docs |
-| `decision:{name}` | Architecture decision records |
-| `ref:{name}` | Reference material |
+| `{project}:sprint:{name}` | Sprint specs and retrospectives |
+| `{project}:state:current` | Current project state |
+| `{project}:arch:{name}` | Architecture docs |
+| `{project}:decision:{name}` | Architecture decision records |
+| `{project}:ref:{name}` | Project reference material |
+| `ref:{name}` | General DevBrain reference material in the `default` project |
 
 ## If You Get No Results
-1. Check casing — project names and keys are case sensitive
-2. Try specifying the project explicitly
-3. Use ListDocuments with no prefix to see what's stored in that project
-4. Try SearchDocuments with a broad keyword
-5. The document may not exist yet — ask the user if they'd like to create it
+1. Check that the key starts with the project name, e.g. `devbrain:state:current`
+2. Check casing — project names and keys are case sensitive
+3. Try specifying the project explicitly
+4. Use ListDocuments with no prefix to see what's stored in that project
+5. Try SearchDocuments with a broad keyword
+6. The document may not exist yet — ask the user if they'd like to create it
 
 ## Frequently Asked Questions