# 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

## Current Foundation

The first concrete foundation for this now exists in AtoCore:

- a project registry file records known project ids, aliases, and ingest roots
- the API can list those registered projects
- the API can refresh a single registered project from its configured roots

This is not full source automation yet, but it gives the refresh model a real
home in the system.

## 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.