Skip to content

Information architecture

Top-level directories (in a derived repo)

DirectoryRoleLifecycle
agents/Domain agent definitionsPermanent
crates/Rust domain computer — connectors, calculators, indexPermanent
packages/Other-language packages (Python, TypeScript)Permanent
web/Web interface layer (optional)Permanent
docs/Repo-level documentationPermanent
.yidam/corpus/The knowledge graph nodesPermanent
.yidam/catalog/Data source provenance nodesPermanent
.yidam/decisions/Structured records of choices made at bootstrap and beyondPermanent
.yidam/sangha/Governance protocol and resolution recordsPermanent
.yidam/skills/Domain-specific reusable agent capabilitiesPermanent
.yidam/.vendor/Inherited yidam prelude; read-only in derived reposPermanent
samudaya/Pre-bootstrap seed layerConsumed at genesis
sadhana/Scaffold templatesConsumed at genesis

Corpus node structure

Each corpus node is a small, focused file:

  • 2–10 sentences is typically right; 40 lines is the hard ceiling
  • One concept per file; one file per concept
  • Kebab-case, descriptive, stable filenames (renaming severs edges)
  • Must have at least one outgoing link
  • Uncertainty is valid if labeled: prefix title with ? or open a branch

Authored nodes — written through deliberate knowledge work. Permanent, non-regenerable.

Generated nodes — produced by a pipeline from a primary source. Regenerable. Committed as operational events, not epistemic events.

Catalog node structure

  • One file per data source
  • Filename: author-year.md for papers, slug.md for datasets/APIs
  • Content: source name, type, location, one-sentence description, access constraints
  • Optional: used-by list of corpus node links for reverse traversal

Ontology class definitions

During bootstrap, the schema layer is written to .yidam/corpus/<class>.ont.yml. What an ontology is explains what a class declares and why. If a foundational ontology was chosen (BFO or UFO) — see choosing an alignment — each class carries a foundational_type field; omit it entirely for "none" alignment:

class: <name>
label: <Human-Readable Label>
foundational_type:           # omit if alignment is "none"
  ontology: bfo | ufo
  type: <bfo or ufo type value>
  iri: <url>                 # optional; exported as skos:exactMatch
description: |
  <one sentence>
properties:
  - name: <field>
    type: string | date | ref | text
    description: <one line>
edges:
  - relationship: <verb phrase>
    target: <class name>
    direction: out | in
    description: <one line>

BFO type values (partial): material-entity, occurrent, process, quality, disposition, role, function, site

UFO type values: kind, subkind, role, phase, relator, mode, quality, event, situation

Corpus instance objects

class: <class-name>
label: <Human-Readable Instance Name>
description: |
  <one or more sentences>
properties:
  <field>: <value>
links:
  - target: ../<other-class>/<other-instance>.yml
    relationship: <verb phrase>
  - target: ../<class>.ont.yml
    relationship: instance-of

Decision records

.yidam/decisions/<slug>.yml:

id: <slug>
summary: <one line>
context: |
  <what the choice was about>
decision: |
  <what was chosen>
rationale: |
  <why this, not alternatives considered>

One record is also read by a tool. .yidam/decisions/kuten.yml records which kuten this corpus adopted, and the revision vendored with it. It carries two extra fields on top of the shape above:

id: kuten
summary: <one line>
kuten: inquiry
revision: 2

yidam kuten, kuten check and doctor read kuten: and revision:; the rest of the record is for a person and for decisions-log. The bootstrap writes it at genesis when the user adopts a profile. A repository with no such record holds no kuten, which is a supported state and is reported as one.

Resolution records

.yidam/sangha/resolutions/<evolution>.md:

---
evolution: <name>
date: <YYYY-MM-DD>
synthesized-by: ma/<elector>
rounds: <how many times the loop ran>
independence: <distinct-seats | shared-configuration | unrecorded>
tips:
  - ma/<elector>@<short-hash>
positions:
  - positions/<elector>-<question>.md
---

## What was resolved
## What changed
## What remains open