ATOCore/docs/project-registration-policy.md

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

And the API template endpoint:

• GET /projects/template

Other lifecycle endpoints:

• POST /projects/proposal
• POST /projects/register
• PUT /projects/{id}
• POST /projects/{id}/refresh