AGENTS.md

This document is the maintenance contract for the .knowledge/ directory.

Purpose

.knowledge/ is the repo-local knowledge base for this project. It mixes:

• wiki-style Markdown notes for interlinked, searchable knowledge;
• preserved long-form Typst documents when document-style exposition is still the right canonical form;
• shared configuration that makes the knowledge base render predictably in Obsidian without making the content Obsidian-specific.

Read First

Before making substantial changes inside .knowledge/:

1. Read _knowledge.index.md.
2. Read organization.md.
3. Read the relevant area index.
4. Read the area's organization.md if one exists (e.g., experiment-reports/organization.md).
5. Read neighboring notes before creating a new note to avoid duplication.

Directory Structure

Top level:

• _knowledge.index.md: root navigation
• AGENTS.md: maintenance contract for agents
• organization.md: top-level orientation note (layout and format policy)
• .obsidian/: tracked knowledge-base config only
• .typst/: shared Typst support files
• assets/: shared reusable assets

Area layout:

• experiments/
• methodology/
• literature/
• ideation/
• theory/
• experiment-reports/
• writing/

Within an area:

• documents/ holds preserved long-form Typst documents
• concepts/ holds atomic Markdown notes
• sequences/ holds preserved ordered note families when reading order matters

Frontmatter

Use this core schema for Markdown notes:

---
type: index|map|note|document|report|setup
status: seed|draft|stable|superseded
aliases: []
created: YYYY-MM-DD
author: Name   # required for atomic notes (`type: note`)
tags: []   # optional
---

Rules:

• type encodes note role, not subject area.
• status encodes maturity/editorial state.
• Use directory path for subject area instead of a frontmatter area field.
• aliases should always be present, even if empty.
• author is required for atomic notes (type: note) and should name the note's author in plain text. Omit it for indexes unless a local area rule says otherwise.
• tags are optional and should be reserved for a small set of cross-cutting themes.
• Do not use updated, source_note, or source_doc in final canonical notes.

Index Conventions

• Root index filename: _knowledge.index.md
• Area and subgroup index filename: _<group>.index.md
• Every index should link to:
  • notes in its folder
  • sub-indexes when the folder has structured subgroups
  • preserved Typst documents where those documents are part of the local knowledge graph

Markdown And Typst Policy

Use Markdown for:

• atomic knowledge notes
• maps and indexes
• experiment reports
• writing notes

Preserve Typst for:

• long-form methodology documents when document-style exposition is still valuable
• long-form ideation documents
• long-form theory documents that should remain readable as standalone papers/essays

Area policy:

• literature/: Markdown-first, organized by project-specific research areas with paper-centric notes and area-level indexes
• methodology/: hybrid
• experiments/: Markdown-first
• ideation/: mixed, with both preserved documents and extracted concept notes
• theory/identifiability/: wiki-first
• theory/strategy_identification/: hybrid with preserved long-form documents
• experiment-reports/: Markdown-first
• writing/: Markdown-first

Prose formatting:

• Do not hard-wrap prose. Write each paragraph as a single line and rely on soft word wrapping in the editor or viewer. This applies to both Markdown and Typst notes. Frontmatter, fenced code, tables, display-math blocks, and list/blockquote structure are unaffected.

Linking

• Use Obsidian wikilinks for internal Markdown references.
• For split note families, add bottom-of-note Next links when reading order matters.
• When referring to paths outside .knowledge/, use literal repo paths in backticks with the path: prefix, for example `path:experiments/...`.
• Preserved Typst documents should still be indexed and linked from nearby Markdown notes or indexes.
• For images that should render in Obsidian, GitHub, and VS Code, prefer standard Markdown image syntax like ![Caption](figures/plot.png) instead of Obsidian-only embeds like ![[plot.png]].

Assets

Asset policy is hybrid:

• shared reusable assets live under assets/<area>/
• local private assets may live next to a report collection or a document when they are not intended for reuse

Do not recreate migration-era asset layouts such as assets/notes/....

Math And Rendering

MathJax:

• preamble path: .obsidian/mathjax/preamble.sty
• Extended MathJax plugin config: .obsidian/plugins/obsidian-latex/data.json
• In Markdown, use $...$ for inline math. Do not use \(...\), which is not reliably valid in this vault's MathJax workflow.

Typst:

• shared support files live in .typst/
• math.typ is the naming reference for mathematical macros
• Markdown math should stay MathJax-compatible, even when macro names mirror Typst/LaTeX style names

Callouts:

• Markdown callout styling lives in .obsidian/snippets/research-callouts.css
• keep display-math delimiters fully inside the block quote when math appears inside a callout

Experiment Reports

The experiment-reports area has its own maintenance contract. See experiment-reports/organization.md for directory layout, hub note requirements, file contracts for design.md / results.md / analysis.md, the authoring guard on interpretive content, figures policy, and the linkage convention to repo-side analysis artifacts. Read that file before creating or restructuring any collection.

Change Discipline

When making substantial changes:

1. Update the relevant local index.
2. Update _knowledge.index.md only when top-level navigation changes.