Clarify source staging and refresh model

docs/source-refresh-model.md

@@ -0,0 +1,89 @@
+# AtoCore Source Refresh Model
+
+## Purpose
+
+This document explains how human-authored project material should flow into the
+Dalidou-hosted AtoCore machine store.
+
+It exists to make one distinction explicit:
+
+- source markdown is not the same thing as the machine-memory layer
+- source refresh is how changes in PKM or repos become visible to AtoCore
+
+## Current Model
+
+Today, the flow is:
+
+1. human-authoritative project material exists in PKM, AtoDrive, and repos
+2. selected high-value files are staged into Dalidou source paths
+3. AtoCore ingests those source files
+4. AtoCore stores the processed representation in:
+   - document records
+   - chunks
+   - vectors
+   - project memory
+   - trusted project state
+5. retrieval and context assembly use the machine store, not the staged folder
+
+## Why This Feels Redundant
+
+The staged source files can look almost identical to the original PKM notes or
+repo docs because they are still source material.
+
+That is expected.
+
+The staged source area exists because the canonical AtoCore instance on Dalidou
+needs a server-visible path to ingest from.
+
+## What Happens When A Project Source Changes
+
+If you edit a note in PKM or a doc in a repo:
+
+- the original source changes immediately
+- the staged Dalidou copy does not change automatically
+- the AtoCore machine store also does not change automatically
+
+To refresh AtoCore:
+
+1. select the updated project source set
+2. copy or mirror the new version into the Dalidou source area
+3. run ingestion again
+4. verify that retrieval and context reflect the new material
+
+## Current Intentional Limits
+
+The current active-project ingestion strategy is selective.
+
+That means:
+
+- not every note from a project is staged
+- not every repo file is staged
+- the goal is to start with high-value anchor docs
+- broader ingestion comes later if needed
+
+This is why the staged source area for a project may look partial or uneven at
+this stage.
+
+## Long-Run Target
+
+The long-run workflow should become much more natural:
+
+- each project has a registered source map
+  - PKM root
+  - AtoDrive root
+  - repo root
+  - preferred docs
+  - excluded noisy paths
+- a command like `refresh p06-polisher` resolves the right sources
+- AtoCore refreshes the machine representation cleanly
+- OpenClaw consumes the improved context over API
+
+## Healthy Mental Model
+
+Use this distinction:
+
+- PKM / AtoDrive / repos = human-authoritative sources
+- staged Dalidou markdown = server-visible ingestion inputs
+- AtoCore DB/vector state = compiled machine context layer
+
+That separation is intentional and healthy.