ATOCore/docs/project-registration-policy.md

AtoCore Project Registration Policy

Purpose

This document defines the normal path for adding a new project to AtoCore.

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

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. add the project entry to the registry
3. verify the entry with:
   • GET /projects
   • or the T420 helper atocore.sh projects
4. refresh it with:
   • POST /projects/{id}/refresh
   • or atocore.sh refresh-project <id>
5. verify retrieval and context quality
6. only later promote stable facts into Trusted Project State

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

And the API template endpoint:

• GET /projects/template