Mosaix Format

A file-level format for knowledge vaults made of atomic, self-describing notes. Machines retrieve one note at a time and have enough context to act. People read many notes as one document. Nothing is silently lost.

START HEREOverview

A Mosaix vault is a folder of Markdown files. Each file is a note, and each note answers exactly one question. Above the body, in YAML frontmatter, every note carries nine keys that a machine reads before the text: a one-sentence summary, search keywords, the named entities, the typed relations between them, the notes it links to, and a hash of the body so that stale metadata can be detected.

Three folders are reserved (_meta/, _synthesis/, _inbox/), one note type composes many notes into a readable document without copying them, and eight rules govern the vault: five are checked from the files, three are commitments the vault makes in writing.

The format fixes what a note carries and which rules the vault obeys. It does not fix how notes are produced, enriched, searched, ranked, composed, or edited. Those are implementations, and different implementations can compete while reading and writing the same vaults.

START HEREQuick start

1. Create the skeleton. A folder with Home.md (the map of content), _meta/Conventions.md, _meta/Open questions.md, and the folders you need. Numbered prefixes (01-, 02-) are a reading order, not a build order.
2. Write one note per question. If a draft answers two questions, split it. Put the nine CORE keys above the body (§3.1). Link every note from at least one other note or from Home.md.
3. Declare your taxonomy. Every tag and every domain key you use goes in _meta/Conventions.md, together with the reliability convention you chose (§3.2) and mosaix: "1.0".
4. Record what you don't know. Contradictions, unconfirmed numbers, open decisions: one entry each in _meta/Open questions.md, with the competing versions, dates, sources and the consequence of choosing.
5. Run the checker. python audit_reference.py path/to/vault. Exit code 0 means conformant. Fix errors note by note; warnings are advice.
6. Compose when people need to read. A note with type: document and fragments lists the notes to read together. The fragments stay separate; the document is the view (§6).

# the smallest conformant vault
my-vault/
├── Home.md                      ← type: moc, links every note
├── _meta/
│   ├── Conventions.md           ← taxonomy, reliability convention, mosaix: "1.0"
│   └── Open questions.md        ← the ledger (R6)
├── _synthesis/
│   └── Overview.md              ← optional: a synthesis to hand to a newcomer or a model
└── 01-Topic/
    ├── First question.md
    └── Second question.md

START HEREVocabulary

§0Status of this document

This document specifies the Mosaix Format, version 1.0. The name comes from the mosaic: every note is a tile that stands on its own, and the picture exists only in the whole. It is licensed under CC BY-SA 4.0: you may copy, adapt and redistribute it, including commercially, provided you credit the author and release derivatives under the same license. The name "Mosaix Format" and its version numbering are part of the specification: a vault may claim conformance to "Mosaix 1.0" only if it satisfies §10.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.

§1Purpose

A vault in this format is a body of knowledge about one domain (a client, a product, a codebase, a project) written so that:

1. a machine can retrieve one note at a time and have enough context to act, without reading the rest of the vault;
2. a human can read many notes as one document, without opening them one by one;
3. nothing is silently lost or overwritten: contradictions are recorded, superseded notes are marked, machine edits are proposed rather than applied.

The format is deliberately small. It fixes what a note carries and which rules the vault obeys. It does not fix how notes are produced, enriched, searched, ranked, composed or edited: those are implementations (§8).

§2Substrate

A Mosaix vault is a directory tree of plain-text files.

• Notes are UTF-8 files with the .md extension containing CommonMark Markdown.
• Each note MAY start with a YAML frontmatter block delimited by --- lines.
• Notes reference each other with wikilinks: [[Note title]], optionally [[Note title|display text]], optionally with a heading [[Note title#Heading]]. A wikilink resolves by the target note's basename without extension, matched case-sensitively, anywhere in the vault.
• Embeds use ![[Note title]] and ![[file.ext]], resolved the same way.
• Tags are #tag or #namespace/tag tokens in the body, or entries of the tags frontmatter list. The two forms are equivalent.

Any tool that reads Markdown files from disk can read a Mosaix vault. No application is required. Obsidian is the reference host application (§9), not a dependency.

§3The note (the "tile")

A note answers one question. If a draft answers two, it is two notes. The body length is not constrained; the scope is.

3.1 Frontmatter — CORE required for conformance

• summary MUST NOT repeat the title and MUST NOT begin with "This note…" or its equivalent. It is written for a reader who has not opened the note.
• Aliases. A vault MAY write any CORE key under an alias declared in its meta note. Recognised by default, so that vaults created before this version stay conformant: mcp_entita → entities, mcp_relazioni → relations, mcp_collegamenti → links, mcp_rev → rev, aggiornato → updated, titolo → title, riassunto → summary, parole_chiave → keywords; inside items, nome → name, tipo → type, da → from, a → to; and the Italian entity-type values (persona azienda prodotto progetto strumento luogo documento evento) map to the English ones. Checkers report by canonical name.
• entities SHOULD list at most 12 items. A note that names more things than that is usually answering more than one question (R1); the checker reports the excess as a warning. MOCs and the meta note are exempt: listing is their job.
• The canonical key order is title · updated · [domain keys] · summary · keywords · entities · relations · links · rev. Tools SHOULD preserve it.
• The body is never touched by metadata operations. Any process that rewrites frontmatter MUST leave the body byte-identical.

---
title: Portwest — player card
updated: 2026-08-12
tags: [player, ppe, competitor]
summary: "Irish PPE manufacturer present in 130+ countries with an own-brand line that undercuts distributors on price; the reference competitor for price."
keywords: [portwest, price competitor, own brand, irish ppe manufacturer, 130 countries, private label]
entities:
  - {name: Portwest, type: company}
relations:
  - {from: Portwest, type: competes with, to: Ateş}
links: [PPE consolidation 2025, Strategic scenarios]
rev: a81c0d33ef21
---
# Portwest — player card

Sells in 130+ countries. Own-brand line undercuts distributors. ✅ sourced (company site, 2026-07).
See [[PPE consolidation 2025]] and [[Strategic scenarios]].

3.2 Frontmatter — reliability axes recommended

Two independent questions, answered by two independent markers. They MAY be expressed as frontmatter keys, as tags, or as inline symbols in the body; a vault MUST choose one convention and document it in its meta note.

A statement may be ✅ sourced and 🟡 not implemented: a verified fact about something that does not yet exist. Keeping the axes separate is what lets a reader, months later, tell an intention from a fact.

3.3 Frontmatter — domain keys per vault

A vault MAY add any keys it needs (campaign, client, country, reliability, stage…). Domain keys MUST be declared in the meta note with their allowed values. Undeclared keys are a conformance warning, not an error.

3.4 Note types

The type key (or a #type/... tag) MAY classify notes. Three types have format-level meaning:

§4Links and the graph

• A note MUST have at least one incoming wikilink from another note, or from a MOC. A note with no incoming link is an orphan and is a conformance error.
• Every wikilink MUST resolve. An unresolved wikilink is a conformance error.
• links is the machine-readable mirror of the note's outbound links. It MAY be a subset of the wikilinks in the body; it MUST NOT contain targets that do not exist.
• The notes, their entities, relations and wikilinks together form the vault graph. The graph is derived from files; it is never the source of truth.

§5Vault structure

5.1 Free layout, reserved names

Folders are free. Numbered prefixes (00-Index, 01-Azienda, …) are a common convention and are read as a reading order, not a build order. Three folder names are reserved:

A vault MAY additionally keep a _private/ folder excluded from version control for personal working material. Nothing in _private/ is part of the vault. Folders holding content exports that are not notes (platform payloads, generated copies) MAY be declared as payload in the meta note and are then excluded from the frontmatter check.

5.2 Synthesis notes

A _synthesis/ note condenses an area of the vault into a text that can be read alone. It MUST link to the notes it summarises. It is the recommended unit to hand to a machine or a newcomer before any task in that area. It is not a substitute for the notes: when it disagrees with a note, the note wins and the synthesis is stale.

5.3 Open questions ledger

The vault MUST have one note that lists what is not yet known or is contradictory. Its canonical location is _meta/Open questions.md (Assunzioni da confermare.md and Domande aperte.md are recognised aliases). Each entry records: the question, the competing versions with their dates and sources, the practical consequence of choosing one over the other, and who is expected to resolve it.

## #12 · Launch date of the online platform
A: 26 Oct 2026   (Roadmap.docx, edited 2026-07-22)
B: 25 Nov 2026   (Master index.md, edited 2026-08-05)
C: 27 Jan 2027   (Timing rules.md, decided with partners 2026-08-29)
consequence: the email schedule shifts by 90 days; every DEM date depends on this
owner: partners · status: C assumed, A and B superseded and kept

5.4 Meta note

The vault MUST have a note (_meta/Conventions.md, or a README.md / CLAUDE.md at the root) that states: the folder contract (which question each folder answers), the reliability convention chosen (§3.2), the domain keys and their values (§3.3), the tag taxonomy with every tag in use, any aliases for CORE keys and any additional entity types, and the people responsible for areas. The taxonomy MAY live in its own note inside _meta/. A tag used in a note and absent from the taxonomy is a conformance warning. The taxonomy is updated in the same change that introduces the tag.

§6Composed documents

Atomic notes are for machines. Humans read documents. The format therefore defines a note type that is a view over other notes without duplicating them. A note with type: document MUST carry:

Its body MAY contain narrative connecting the fragments and MAY embed them with ![[Note]]. The rule is: the fragments stay atomic and separate; the document is only the view that joins them. An edit made while reading the composed document belongs to the fragment's note, not to the document. Because the composed document is itself a note, it inherits versioning, review, search and linking for free. No second storage channel is needed.

---
title: Market entry brief — PPE, Europe
type: document
updated: 2026-09-03
tags: [composed-document, brief]
summary: "Board-ready brief on entering the European PPE market, assembled from five notes: consolidation, the price competitor, an open question, the fair calendar and the recommended scenario."
keywords: [market entry brief, ppe europe, board document, composed brief, five fragments, reading order]
fragments: [PPE consolidation 2025, Portwest — player card, Open question #33 — Albania, PPE trade fairs Europe 2026, Strategic scenarios]
pool: [Turkish footwear cost model]
layout:
  cover: {title: Market entry brief — PPE, Europe, subtitle: Board reading, date: 2026-09-03}
  page: A4
  sections:
    - {title: Market, fragments: [PPE consolidation 2025, Portwest — player card]}
    - {title: What we do not know, fragments: [Open question #33 — Albania]}
    - {title: Recommendation, fragments: [PPE trade fairs Europe 2026, Strategic scenarios]}
  show: [summary, status]          # what of each fragment's frontmatter is printed
links: [PPE consolidation 2025, Portwest — player card, Open question #33 — Albania, PPE trade fairs Europe 2026, Strategic scenarios]
rev: 2233bbcc44dd
---
# Market entry brief — PPE, Europe

Read the five fragments in order. ![[PPE consolidation 2025]] …

layout is free-form: the keys above are the ones the reference implementations use (cover, page, sections, show). A tool MUST ignore layout keys it does not understand, and a document with no layout is printed as its fragments in order.

§7Rules of the vault

A conforming vault obeys the following. R1–R5 are verifiable from files; R6–R8 are process rules the meta note commits to.

• R1
  Atomicity

  One note answers one question. If a draft answers two, it is two notes.

• R2
  Self-description

  Every note carries the CORE frontmatter (§3.1).

• R3
  Connectedness

  No orphans, no broken links (§4).

• R4
  Declared taxonomy

  Every tag and every domain key is declared in the meta note (§5.4).

• R5
  Composition over duplication

  Content that must be read together is joined with a composed document (§6) or a synthesis (§5.2), never copied.

• R6
  Record, don't resolve

  A contradiction between notes is entered in the open-questions ledger with both versions. Nobody picks a winner silently. Numbers, prices, dates and commitments to third parties are never chosen on behalf of the owner.

• R7
  Supersede, don't delete

  A note that is no longer valid is marked superseded (status: superseded, #status/archived, or a banner) and left in place, because other notes link to it. Deletion is reserved for notes that were created in error.

• R8
  Propose, don't apply

  Any automated process that writes to the vault writes to a branch, a pull request, or a staging area that a human reviews. Automated processes never write to the vault's main line. rev is the mechanism that lets a reviewer see whether a proposal was made against the current body.

§8Out of scope

The following are not defined by this specification. They are implementations, and different implementations may compete on them while producing and consuming conformant vaults:

• how summary, keywords, entities, relations, links are generated (enrichment);
• how documents are turned into notes (ingest, splitting, deduplication);
• how notes are retrieved for a task (search, ranking, embeddings, context budgets);
• how composed documents are edited, paginated or printed (editors);
• how the vault is exposed to agents (MCP tools, APIs) or synchronised (git, mirrors);
• how the graph is visualised.

A vault produced by hand, with no tooling, can be fully conformant.

§9Host application profile: Obsidian

Obsidian is the reference host: its wikilink and embed resolution, tag syntax and frontmatter handling match §2 exactly. A vault MAY additionally use Obsidian features; they are outside the format and MUST NOT be required by any rule:

• Dataview queries, Bases (.base), Canvas, map plugins: views, not content. They SHOULD live inside notes so they are versioned with the vault.
• Callouts (> [!tip]): a vault MAY assign meaning to callout kinds; if so, the meaning is documented in the meta note.
• The .obsidian/ folder is host state, not vault content; workspace.json SHOULD be excluded from version control.

Other hosts known to read the substrate: Logseq, Foam, Dendron, Zettlr, and Markdown editors with wikilink extensions.

§10Conformance

A vault is Mosaix 1.0 conformant when a check over its files reports zero errors for:

and zero or more warnings for: tags not declared in the taxonomy, domain keys not declared, rev older than the body (stale metadata), notes without any reliability marker, more than 12 entities on a note that is not a MOC. A reference checker, audit_reference.py, accompanies this specification. It uses only the Python standard library and produces the table above. Its output is the conformance report.

§11Versioning of this specification

Versions follow MAJOR.MINOR.PATCH. A MINOR version may add optional keys, note types or warnings; it never turns a conformant vault into a non-conformant one. A MAJOR version may. Vaults SHOULD state the version they target in their meta note (mosaix: "1.0").

§12Provenance

The format was extracted from three vaults in production use (code documentation, industrial market intelligence, education marketing), by measuring which conventions each had invented and keeping the intersection that a machine could rely on. Those vaults used Italian key names; they are kept as default aliases so that they remain conformant unchanged. The two-axis reliability model, the open-questions ledger and the supersede-don't-delete rule come from the practice of working with several sources of different dates. The composed-document type comes from the observation that a vault of good atomic notes is unreadable by the people who need it most.

REFERENCEMeta note syntax

Everything a vault declares about itself lives in the meta note's frontmatter, so that a checker can read it. Prose in the body explains; the keys below are what tools use. All are optional except mosaix. This block is part of 1.0: the reference checker reads aliases, entity_types, relation_types, payload, and tags as the vault's taxonomy.

---
title: Conventions
type: meta
updated: 2026-09-03
tags: [meta, conventions]
summary: "Conventions of this vault: folders, reliability, taxonomy, domain keys, aliases, payload folders, maintainers."
keywords: [conventions, meta, taxonomy, folders, reliability, aliases, payload, maintainers]
rev: 0a1f3c9e7b21
mosaix: "1.0"                          # target version
folders:                                # which question each folder answers
  01-Company: who they are
  02-Market: where they sell
  _docs: composed documents
reliability:                            # the convention chosen for §3.2
  key: status
  values: [sourced, to-confirm, superseded]     # axis A; add axis B values if the vault builds things
tags: [moc, meta, ledger, player, market, fairs, strategy, open-question]   # every tag in use
domain_keys:                            # §3.3, with allowed values or a type
  client: string
  country: ISO-3166 alpha-2
  stage: [prospect, active, closed]
aliases:                                # CORE keys in the vault's language
  aggiornato: updated
entity_types: [department, regulation]  # added to the eight of §3.1
relation_types: [owns, supplies, competes with, depends on]   # optional; closed vocabulary if given
payload: [exports/, 07-Sources-raw/]    # folders excluded from the frontmatter check
maintainers:
  - {name: A. Fiorino, area: market}
---
# Conventions
Prose: how to write here, who decides what, how to record a contradiction.

A checker that finds these keys uses them; a checker that does not still applies the defaults (the eight entity types, the default aliases, no payload folders). Nothing here changes the notes: it only tells tools how to read them.

REFERENCEAnatomy of a real vault

A market-intelligence vault of about 150 notes, as it looks in production. The numbered prefixes are a reading order; each folder answers one question, declared in the meta note. Entity notes (players, brands, partners) are ordinary notes whose title is the entity's canonical name, so that entities can point to them.

vault/
├── Home.md                          type: moc · the map: one paragraph per area, links to the area MOCs
├── _meta/
│   ├── Conventions.md               folders, reliability, tags, domain keys, payload
│   ├── Open questions.md            the ledger · 33 entries, each with versions and consequence
│   └── Tag index.md                 the taxonomy with a line per tag (optional split)
├── _synthesis/
│   ├── Company in one page.md       read before any task about the company
│   └── Market in one page.md
├── _docs/
│   └── Market entry brief.md        type: document · 5 fragments · what the board reads
├── 01-Company/                      who they are
│   ├── Profile.md · History and governance.md · Sites and logistics.md
├── 02-Brands/                       what they sell, one note per brand
├── 03-Partners/                     who they sell with, one note per partner
├── 04-Market/                       where they could sell
│   ├── PPE market Europe.md · Consolidation 2025.md · Trade fairs 2026.md · Regulation.md
├── 05-Opportunities/                what they could do
│   ├── Assessment.md · Strategic scenarios.md
├── 06-Sources/                      what we relied on, with reliability per source
│   └── Source reliability.md
├── 07-Sources-raw/                  payload · extracts and originals, not notes
├── 09-Players/                      one note per competitor: the entity notes
│   ├── Portwest.md · Delta Plus.md · Uvex.md · …
└── assets/                          images and PDFs embedded with ![[ ]]

Reading path for a newcomer: Home → the two syntheses → the composed brief → the notes it cites. Reading path for a machine: the summaries of the MOC's links, then the one note the task needs and its links. For a smaller, self-contained example on an everyday domain, download the bakery vault: 26 notes about a fictional artisan bakery, fully conformant.

REFERENCEMigrating an existing vault

Almost nobody starts from zero. A vault of Markdown notes with wikilinks is already most of the way there; what is usually missing is the frontmatter, the taxonomy and the governance notes. Do it in this order, running the checker after each step: the error count is the progress bar.

1. Run the checker once, as is. Note the numbers. A typical untouched vault of 150–200 notes reports 70–100 errors and several hundred warnings; almost all warnings are undeclared tags, almost all errors are missing frontmatter and orphans.
2. Create the two governance notes. _meta/Conventions.md with mosaix: "1.0" and, for now, the list of tags already in use (collect them with any tag pane or a grep for #). _meta/Open questions.md, empty is fine. This alone clears the warnings.
3. Make sure there is a map. If Home.md or an index exists, give it type: moc and link every area from it. Orphans drop as you go.
4. Declare payload folders. Exports, raw sources, generated copies: list them under payload: so they stop counting as notes.
5. Add frontmatter area by area. Start with the notes the map links first. summary and keywords by hand or with a tool; rev only when a tool computes the keys, otherwise leave it and accept the warning. Split any note that answers two questions.
6. Record instead of fixing. Every contradiction you find while adding frontmatter goes in the ledger with both versions. Do not pick a winner while migrating.
7. Fix links, then declare conformance. Broken links and remaining orphans last. When the checker exits 0, state the version in the meta note and, if you like, add the badge: ![Mosaix 1.0 conformant](https://mosaixformat.org/badge.svg). The badge is a claim you make about your own vault; the checker report is the evidence.

Expected numbers, from two real migrations: 71 errors and 646 warnings before; 9 errors (all orphans) and 3 warnings after steps 2–4, before touching a single note body.

A vault written in another language

Nothing has to be renamed. A vault that already uses its own key names declares them once in the meta note and is checked as if it used the canonical ones. The Italian names below are recognised even without this block (§3.1); the block is what you write for any other language.

---
title: Metodo e convenzioni
type: meta
mosaix: "1.0"
aliases:                     # your key → canonical key
  aggiornato: updated
  riassunto: summary
  parole_chiave: keywords
  mcp_entita: entities
  mcp_relazioni: relations
  mcp_collegamenti: links
  mcp_rev: rev
  tipo: type
  stato: status
reliability: {key: stato, values: [ok, confermare, superato]}
tags: [moc, meta, player, mercato, fiere]
---

Values map too: tipo: azienda is read as type: company, stato: confermare as status: to-confirm. The checker reports every finding with the canonical name, so a report is comparable across vaults in different languages.

REFERENCEFile names and characters

Wikilinks resolve by file name, so the file name is the note's identity until a stable id exists (under discussion for 1.1).

• Title and file name coincide. title: Portwest — player card lives in Portwest — player card.md. Renaming one means renaming the other and every link; hosts like Obsidian do this for you, the format does not.
• Characters to avoid: : / \ ? * " < > | (forbidden on Windows) and a trailing dot or space. # and | also break wikilink syntax. §, accents and the em dash are fine on every current system; keep them if they are the natural title.
• Case is significant in links. Pick one convention (sentence case works) and keep it.
• Length: under 80 characters. Long titles belong in the body's first heading, not in the file name.
• Duplicates: two notes with the same basename in different folders are ambiguous for every host. Make titles unique across the vault.

REFERENCEAttachments and images

Files that are not notes (images, PDFs, spreadsheets) live in one folder, conventionally assets/, and are embedded with ![[chart.png]] or ![[report.pdf]]. They do not count toward conformance, need no frontmatter, and are not checked. A note that exists only to describe an attachment is still a note: it carries the CORE keys and links to the file. Keep attachments out of _meta/, _synthesis/ and _inbox/.

REFERENCEEntity types

The eight types of entities, and where the line is. A vault may add types in its meta note; it may not redefine these.

Relation phrases (relations[].type) are short verbs in the present tense from the first entity's point of view: owns, supplies, competes with, depends on, takes part in. Declare a closed list in the meta note if you want deterministic queries.

REFERENCEScale

• Up to a few hundred notes: one map of content and a few syntheses are enough. The checker runs in under a second.
• Around a thousand: give each area its own MOC and link the area MOCs from Home. Keep entity notes in one folder so entities has a single place to point to.
• Several thousand: the format holds (it was exercised at a thousand notes with flat per-note context), but a hand-maintained taxonomy and ledger need tooling. That tooling is out of scope for the format and is where implementations differ.

The per-note context stays constant whatever the vault size: a note and its direct dependencies are the same few hundred tokens at 50 notes and at 5,000. What grows is the map, and maps are cheap.

REFERENCEThe checker

audit_reference.py is a single Python 3.10+ file with no dependencies. It reads the vault, never writes to it, and prints the conformance report. Exit code 0 means conformant, 1 means errors were found.

python audit_reference.py path/to/vault
python audit_reference.py path/to/vault --verbose            # errors and warnings, note by note
python audit_reference.py path/to/vault --json               # machine-readable report
python audit_reference.py path/to/vault --exclude=exports/   # skip payload folders (comma-separated prefixes)
python audit_reference.py path/to/vault --check-rev          # also flag rev that no longer matches the body (hint only)

Mosaix 1.0 audit — path/to/vault
notes: 141  errors: 0  warnings: 12
CONFORMANT

The checker recognises the default aliases (aggiornato, titolo, riassunto, parole_chiave), reads the taxonomy from any note in _meta/ (or a note named Conventions, Indice tag, Tag index, README, CLAUDE), and treats Home, 00-Index, Index or any note containing "moc" as maps of content.

Check on every push

A GitHub Action wraps the checker so that every push and pull request is verified automatically. Add this workflow to your repository:

name: Mosaix
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: mosaix-format/spec@v1.0.0
        with: { vault: ., exclude: "exports/" }

The action posts the conformance report as a comment on every pull request and fails the check if the vault is not conformant. Display the badge https://mosaixformat.org/badge.svg only when this check is green.

The JSON report

{
  "vault": "/path/to/vault",
  "notes": 141,
  "errors": ["04-Market/Trade fairs 2026.md: keywords count 9 (6–8)", "…"],
  "warnings": ["09-Players/Uvex.md: tag #dpi not declared in meta note", "…"],
  "conformant": false
}

Each message is path: message; vault-level findings start with vault:. The shape is stable within 1.x, so it can drive a badge, a CI check or a dashboard.

REFERENCENote templates

A note

---
title:
updated: 2026-09-03
tags: []
summary: ""
keywords: []
entities: []
relations: []
links: []
rev:
---
#

The map of content (Home.md)

---
title: Home
type: moc
updated: 2026-09-03
tags: [moc]
summary: "Map of content of the vault: where to start, the areas, the syntheses, the ledger and the composed documents."
keywords: [home, map of content, index, where to start, entry point, areas]
links: [Overview, Open questions, Conventions]
rev:
---
# Home

Start with [[Overview]]. Areas: … Open: [[Open questions]]. Conventions: [[Conventions]].

The meta note (_meta/Conventions.md)

---
title: Conventions
type: meta
updated: 2026-09-03
tags: [meta, conventions]
summary: "Conventions of this vault: folder contract, reliability markers, declared tags and domain keys, entity types, aliases, maintainers, target version."
keywords: [conventions, meta note, taxonomy, folder contract, reliability, tags, maintainer, mosaix version]
rev:
---
mosaix: "1.0"
## Folders
01-… answers … · 02-… answers …
## Reliability
Frontmatter key `status`: sourced · to-confirm · superseded
## Tags
moc, meta, … (every tag in use)
## Domain keys
cliente (string) · paese (ISO code) · …
## Maintainers
…

The ledger (_meta/Open questions.md)

---
title: Open questions
type: ledger
updated: 2026-09-03
tags: [meta, ledger]
summary: "Ledger of what is not decided or is contradictory: one entry per question with the competing versions, dates, sources, consequence and owner."
keywords: [open questions, ledger, contradictions, undecided, to confirm, assumptions, owner]
rev:
---
## #1 ·
A:  (source, date)
B:  (source, date)
consequence:
owner:  · status: open

A composed document

---
title:
type: document
updated: 2026-09-03
tags: [composed-document]
summary: ""
keywords: []
fragments: [Note A, Note B, Note C]
links: [Note A, Note B, Note C]
rev:
---
#

![[Note A]]
![[Note B]]
![[Note C]]

REFERENCEErrors and warnings

REFERENCEWorking with agents

The format is designed so that an agent never needs the whole vault. The unit of work is a cluster: one note plus its direct dependencies, resolved from links and relations, usually a few hundred tokens. A planner reads the map of content and the summaries, picks one tile per agent, and hands each agent its cluster. Agents run in parallel; there is no shared memory to keep in sync. Their results are new or revised tiles, proposed on a branch (R8) and composed with a document note.

Three consequences follow. The model is a per-agent choice: a small local model for the tiles it passes, a vertical model where the domain needs it, a large model only where nothing smaller will do. A stale rev tells the reviewer that a proposal was made against an old body. And the ledger (R6) is where an agent records a contradiction it finds, instead of resolving it.

REFERENCECompared with

Mosaix is a file-level format. It does not compete with editors, retrieval systems, or graph databases. It competes with the absence of a format: the situation where every vault invents its own conventions and no tool can assume anything about the files it reads. The table below places Mosaix next to things people already use, honestly.

Using them together. Mosaix vaults are Markdown files; they open in Obsidian, Logseq, Foam, Dendron and any editor that reads wikilinks. A RAG pipeline can index the same files. An llms.txt can be generated from the map. JSON-LD can be derived from the entities and relations. The format adds a layer of structure to files that already work everywhere, and takes nothing away.

REFERENCEFAQ

My vault uses mcp_entita, tipo, stato…

It is conformant as it is. The format was extracted from Italian vaults; those names are default aliases (§3.1) and the checker reports them by their canonical English name. Any other alias can be declared in the meta note.

Do I need Obsidian?

No. Any Markdown tool reads a vault. Obsidian is the reference host because its link resolution matches §2 exactly.

Can I keep long notes?

Length is not constrained; scope is. One question per note. If a note answers two questions, split it and link the halves.

Who computes rev?

A tool, when it writes entities, relations and links. By hand, leave it and accept the warning; the checker only needs it present.

My vault has hundreds of notes without frontmatter.

Run the checker with --verbose, fix the MOC and the meta note first, then add frontmatter area by area. The checker tells you exactly where you are.

Is a vault produced by hand conformant?

Yes. Conformance is a property of the files (§10), not of any tool.

What happens to my vault's content when I run the checker?

Nothing leaves your machine. audit_reference.py is a single file that reads the vault from disk, writes nothing, opens no network connection and has no dependencies. Read it before running it: it is 393 lines. The same is true of the specification: it defines files, not a service, and there is no account, telemetry or upload anywhere in it.

Can I use the format for confidential material?

The format has no opinion on where files live. A conformant vault can sit in a private repository, on an encrypted disk, or air-gapped. What the format asks — _private/ outside version control, machine edits as proposals, superseded notes kept — tends to make audit trails easier, not harder.

How do I propose a change to the specification?

Open an issue on the repository describing the case the current text gets wrong, with a note or a vault excerpt. Changes land as a pull request on Mosaix-Format-v1.0.en.md (English is normative), with a CHANGELOG line and, if a check changes, the matching edit to the checker. Additions that keep every conformant vault conformant go in a MINOR version; anything else waits for the next MAJOR (§11).

REFERENCELicense and citation

The specification and the reference checker are licensed under CC BY-SA 4.0. Credit "Mosaix Format, Andrea Fiorino". The names "Mosaix" and "SLIM", the tooling that produces, enriches, searches or composes vaults, and any vault content are not covered by this license. Conformance claims ("Mosaix 1.0 conformant") are permitted only for vaults that pass the checks in §10.

Fiorino, A. (2026). Mosaix Format — Specification v1.0.0. Boom Digital.
https://mosaixformat.org — source: mosaix-format/spec@v1.0.0

Cite the tagged version, not the page: the tag is immutable, the page follows the latest MINOR. A DOI for each tagged release is planned (see What's next); until then the git tag is the stable reference.