AGENTS.md

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 structure.md.
  3. Read the relevant area index.
  4. Read neighboring notes before creating a new note to avoid duplication.

Directory Structure

Top level:

  • _knowledge.index.md: root navigation
  • log.md: chronological maintenance log
  • AGENTS.md: maintenance contract for agents
  • structure.md: human-facing orientation note
  • .obsidian/: tracked knowledge-base config only
  • .typst/: shared Typst support files
  • assets/: shared reusable assets

Area layout:

  • methodology/
  • 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
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.
  • 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:

  • methodology/: hybrid
  • 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

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

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

  • Canonical report format is Markdown.
  • Organize reports to mirror the repo's experiment families.
  • Use collection-local asset directories when report figures are private to a collection.
  • Do not treat methodology notes as experiment reports.

Cleanup Rules

  • Remove migration-only wording from notes that have become canonical.
  • Remove migration helper notes when they are no longer operationally needed.
  • Preserve original language where possible, but normalize broken syntax and notation.
  • Avoid duplicate concept notes when a nearby note already covers the concept cleanly.

Change Discipline

When making substantial changes:

  1. Update the relevant local index.
  2. Update _knowledge.index.md only when top-level navigation changes.
  3. Add a short entry to log.md for structural migrations, major ingest/refactor passes, or other material maintenance operations.
Built with LogoFlowershow