`knowledge-layer/assets/template/SCHEMA.md`

65 lines
# Schema

This Knowledge Layer is a plain-directory, LLM-compiled wiki. The **structure is
the index** — there is no vector database. Agents read the relevant entries
first, then act.

_Initialized: {{DATE}}_

## Typed folders

Every entry lives in exactly one typed folder: **{{FOLDERS}}**.

One entity/concept per file. Narrow scope beats a sprawling page — a small,
sharp entry is easier to keep correct than a giant one.

## Entry file format

`<folder>/<slug>.md`, kebab-case slug, YAML frontmatter + markdown body:

```markdown
---
id: acme-corp
type: company
tags: [vendor, saas, active]
aliases: ["ACME", "Acme Inc."]
sources: [sources/discovery-call-2026-05-01.md, sources/contract.pdf]
updated: 2026-05-02
---
# ACME Corp

**Summary:** SaaS vendor we onboarded May 2026; primary contact [[jane-doe]].

## Facts
- Founded 2019, HQ Lisbon. <!-- src: discovery-call-2026-05-01 -->
- Net-30 terms, 15% partner discount. <!-- src: contract -->

## Open questions
- Renewal date not yet confirmed.

## Related
- [[jane-doe]] — CEO / our contact
- [[onboarding-playbook]]
```

### Frontmatter fields
| field | required | meaning |
|-------|----------|---------|
| `id` | yes | stable slug, matches filename |
| `type` | yes | one of the typed folders |
| `tags` | recommended | lowercase facets for retrieval/filtering |
| `aliases` | recommended | alternate names → boosts `kl_query.py` recall |
| `sources` | **yes** | provenance: which `sources/` files back this entry |
| `updated` | yes | ISO date of last compile touch |

### Body conventions
- `**Summary:**` one line — agents read this first, drill down on demand.
- Per-fact provenance with an inline `<!-- src: <source-stem> -->` comment.
- Cross-reference related entries with `[[slug]]` wikilinks.
- Contradictions do NOT get resolved silently here — log them in
  `CONTRADICTIONS.md` and cite both sources.

## Evolving the schema
Add a new typed folder only when a real category emerges (not speculatively).
Record the addition here so the compile agent routes future material correctly.