# AtoCore Project Registration Policy

## Purpose

This document defines the normal path for adding a new project to AtoCore and
for safely updating an existing registration later.

The goal is to make `register + refresh` the standard workflow instead of
relying on long custom ingestion prompts every time.

## What Registration Means

Registering a project does not ingest it by itself.

Registration means:

- the project gets a canonical AtoCore id
- known aliases are recorded
- the staged source roots for that project are defined
- AtoCore and OpenClaw can later refresh that project consistently

Updating a project means:

- aliases can be corrected or expanded
- the short registry description can be improved
- ingest roots can be adjusted deliberately
- the canonical project id remains stable

## Required Fields

Each project registry entry must include:

- `id`
  - stable canonical project id
  - prefer lowercase kebab-case
  - examples:
    - `p04-gigabit`
    - `p05-interferometer`
    - `p06-polisher`
- `aliases`
  - short common names or abbreviations
  - examples:
    - `p05`
    - `interferometer`
- `description`
  - short explanation of what the registered source set represents
- `ingest_roots`
  - one or more staged roots under configured source layers

## Allowed Source Roots

Current allowed `source` values are:

- `vault`
- `drive`

These map to the configured Dalidou source boundaries.

## Recommended Registration Rules

1. Prefer one canonical project id
2. Keep aliases short and practical
3. Start with the smallest useful staged roots
4. Prefer curated high-signal docs before broad corpora
5. Keep repo context selective at first
6. Avoid registering noisy or generated trees
7. Use `drive` for trusted operational material when available
8. Use `vault` for curated staged PKM and repo-doc snapshots

## Normal Workflow

For a new project:

1. stage the initial source docs on Dalidou
2. inspect the expected shape with:
   - `GET /projects/template`
   - or `atocore.sh project-template`
3. preview the entry without mutating state:
   - `POST /projects/proposal`
   - or `atocore.sh propose-project ...`
4. register the approved entry:
   - `POST /projects/register`
   - or `atocore.sh register-project ...`
5. verify the entry with:
   - `GET /projects`
   - or the T420 helper `atocore.sh projects`
6. refresh it with:
   - `POST /projects/{id}/refresh`
   - or `atocore.sh refresh-project <id>`
7. verify retrieval and context quality
8. only later promote stable facts into Trusted Project State

For an existing registered project:

1. inspect the current entry with:
   - `GET /projects`
   - or `atocore.sh projects`
2. update the registration if aliases, description, or roots need refinement:
   - `PUT /projects/{id}`
3. verify the updated entry
4. refresh the project again
5. verify retrieval and context quality did not regress

## What Not To Do

Do not:

- register giant noisy trees blindly
- treat registration as equivalent to trusted state
- dump the full PKM by default
- rely on aliases that collide across projects
- use the live machine DB as a source root

## Template

Use:

- [project-registry.example.json](C:/Users/antoi/ATOCore/config/project-registry.example.json)

And the API template endpoint:

- `GET /projects/template`

Other lifecycle endpoints:

- `POST /projects/proposal`
- `POST /projects/register`
- `PUT /projects/{id}`
- `POST /projects/{id}/refresh`