130 lines
3.4 KiB
Markdown
130 lines
3.4 KiB
Markdown
# 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`
|