Spec: what is a standard Astrolabe project? (layout, projects home, extraction tooling)

[Xinze-Li-Moqian]

Motivation

Any repo should be able to carry knowledge as an .astrolabe store and be opened by the engine. Today the shape is implicit — learned from the two existing stores (the docs store, the riemannian store) and the engine's internal docs. Now that sites assemble the engine and mount projects, we need a written contract: what exactly constitutes a standard Astrolabe project?

Current de-facto layout

<project>/
└─ .astrolabe/
   ├─ atoms/    one card per file, named by hash
   ├─ edges/    same
   └─ docs/     *.mdx pages — no knowledge, only hash references

Plus the layered variant (a project without its own atoms/ reads the shared hypergraph/ pool). Lean/tex/bib are record fields (source:), not directories — source code lives in the host repo, cards reference it.

Proposal to discuss

Standardize a projects home — inside or beside .astrolabe — that holds:

1. the projects themselves (the stores), and
2. their automated extraction tooling: the scripts that derive/refresh cards from the host sources (e.g. Lean → source: lean atoms). The old Python tools/ were retired with store mechanics converging on Node (storeOps); Lean ingestion is due to be rebuilt in Node — this spec should decide where such tools live and what contract they follow (write through storeOps, idempotent, runnable at build time?).

Questions to settle

• Canonical store layout spec: atoms/edges/docs, record formats (nested vs flat), hashing rules, the five well-formedness invariants — written as a normative doc (the docs store's 01-the-store.mdx "On disk" section is the natural home).
• Where a project lives in a host repo: top-level .astrolabe/ (OpenGALib style) vs projects/<name>/.astrolabe/ (engine style) — or both, with discovery rules.
• Extraction tooling: location (.astrolabe/tools/? <project>/tools/?), interface, and whether the engine/assemble step runs it.
• Validation story: linter/CI checks for the invariants.
• How the engine addresses projects: filesystem path today, URL (open-by-URL) later — the spec should be transport-agnostic.